Comencé a usar Notion hace casi un año (en el 2021) para manejar mi contenido de Youtube, me ha gustado mucho el producto y la manera tan sencilla de organizar mis ideas, scripts, diario personal, etc. Así que decidí usarlo también para mi blog personal.

Uno de los retos fue lograr mostrar la información de Notion a mi página web, pero afortunadamente Notion cuenta con una API Rest que te da acceso a todo el contenido que tengas. En este tutorial voy a mostrar los pasos necesarios para que tú también puedas hacerlo si gustas.

Durante años mi blog ha sido un Wordpress sencillo, así que ya tenía varios posts publicados y era necesario traerlos a Notion, lo cual no fue del todo sencillo porque lo intenté de varias maneras sin tener éxito. 

Afortunadamente encontré un plugin para Wordpress que se llama 

. Este plugin nos permite exportar todos nuestros posts en formato CSV dando click a un botón. 

Una vez que descargué mi contenido a mi local, importarlo en Notion es bastante sencillo. Solo basta ir a la colección donde lo quieres importar y dar click sobre la opción 

 que se encuentra en el menu superior derecho, se abre una ventana modal donde vienen varias opciones, entre ellas la opción de CSV.

Algunos posts que importé tenían imágenes o porciones de código, el plugin exportador solamente me generó el CVS con HTML en el campo de contenido, por lo tanto algunos posts no se veían del todo bien. Una de las características de Notion es que permite usar markdown, así que usé una herramienta para convertir 

Sólo tenía unos pocos posts, de tener cientos habría automatizado el proceso, muy probablemente haciendo un script y usando el API de Notion para insertar cada registro.

Una vez listo el contenido ¡es hora de comenzar a programar! Para este proyecto decidí usar 

En primer lugar porque quería aprender a usar este framework. 

Está basado en React, así que no tenía que aprender esa parte.

Permite generar sitios estáticos que se pueden deployar a Github Pages, esto es importante para el SEO, además de que no quería mantener un servidor web.

Es bastante popular y con buena documentación, importante para cuando es necesario buscar ayuda.

. Ya he usado Gatsby, pero la verdad es que no tenía claro como integrar el API de Notion con GraphQL, además de que mis ganas por aprender Nextjs fueron más. 

AstroJS se ve bastante interesante, pero adicionalmente a aprender el framework, no usa React, así que tenía que aprender su propia manera de hacer componentes, y la verdad es que tampoco le quería dedicar mucho tiempo a este proyecto.

Iniciarte con NextJS es bastante sencillo, yo decidí usar Typescript y solamente tuve que 

Siempre que es mi decisión, decido usar Tailwind CSS para la parte de los estilos. 

 es bastante sencillo, solo me bastó con seguir la documentación y en cuestión de minutos tenía Tailwind funcionando correctamente.

Lo siguiente es sacar la información de Notion usando el API disponible, para esto es necesario 

 en tu cuenta de Notion. Yo le di acceso de solo lectura porque no voy a escribir nada, esta integración es para mi blog. Una vez que creaste la integración te van a dar un Secret Key, este lo vas a usar en todos tus requests para autenticarte y acceder a tu información.

Una vez que tienes tu integración es necesario asignarla a una 

, Notion así les llama a las colecciones/folders que tienes para organizar tu información. Lo que tienes que hacer aquí es ir a la colección y en el menú superior derecho, hay una opción que se llama 

, en esta sección hay una opción que dice 

, te aparece un submenu con varias opciones, entre una de ellas estará la integración que creaste, selecciona esa y listo.

Por último necesitar el ID de la base de datos. Este lo vas a usar en cada request que hagas al API. La documentación no dice nada al respecto de cómo obtener este ID, yo estuve un buen rato buscándolo y jalándome los pelos. Pero lo puedes sacar de la URL de la colección, por ejemplo, la URL de la colección de mi blog es la siguiente:

https://www.notion.so/crysfel/4b751e1cdfe1471b97912bceee115156?v=38bb03c48f0a42c79b8c84ea4a7c2800

. Ese es el ID que vamos a necesitar más adelante para sacar todos los artículos publicados.

Ya que tenemos el Secret Key y el Database ID, estamos listos para comenzar a llamar el API. Te recomiendo usar Postman para probar que tus peticiones funcionen bien.

En cada post, he creado una propiedad llamada 

, esta propiedad tiene varios valores, por ejemplo: Idea, Draft, Review y Publish. Tengo un lindo board donde voy moviendo las tarjetas en entre estas columnas.

Ahora bien, quiero leer solamente aquellos posts que estén con 

. Además los quiere ordenados por lo últimos que he publicado.

Aquí tuve un problema porque la documentación de Notion no es muy clara, tiene varios endpoints pero no vi por ningún lado como sacar justo la información que necesitaba, así que me puse a probar todos. Resulta que se debe usar 

, y tiene sentido una vez que sabes que Notion le llama database a las colección, pero en ese momento no lo sabía y si me tardé un buen rato.

Bueno, la petición para este ejemplo sería la siguiente.

POST https://api.notion.com/v1/databases/[DATABASE_ID]/query

Body Payload:
  {
    "page_size": 20,
    "filter": {
        "and": [
            {
                "property": "Status",
                "select": {
                    "equals": "publish"
                }
            },
            {
                "property": "Type",
                "select": {
                    "equals": "post"
                }
            }
        ]
    },
    "sorts": [
        {
            "property": "Date",
            "direction": "descending"
        }
    ]
}

Como se puede observar, se puede definir el número de posts que quieres traer por cada consulta, así como filtros. En mi caso tengo varios tipos de posts, proyectos, books, etc. Así que para el blog solamente quiere traer los de tipo 

No olvidar mandar el Secret Key en la cabecera 

 del request, también es necesario mandar el 

 como parte de los headers, de lo contrario vas a recibir un error. En la 

Esa petición trae todos los post con la mayoría de información, pero falta lo más importante, el contenido principal. Para traer el contenido tienes que hacer otra petición por cada post al siguiente endpoint.

GET https://api.notion.com/v1/blocks/[POST_ID]/children

. La respuesta de este endpoint será un JSON con todo el contenido, cada párrafo es un bloque que a su vez puede tener otros bloques, dependiendo como has formateado el contenido.

El siguiente problema que me encontré fue como hacer para guardar la información en local, ya que la voy a usar en varios lugares y además solo la voy a usar al momento de generar todos los HTML estáticos, ya que no voy a usar un servidor web con Node, todo será HTML y CSS para que mi sitio vuele.

Decidí hacer un script que consultara la API de notion, sacara toda la información y me guardara un archivo JSON en mi local, de esta manera al desarrollar solamente leería el archivo JSON desde Nextjs y listo, todo mi contenido estaría disponible y listo para ser usado.

El script es bastante sencillo, solo hace una petición inicial a Notion para traer todos los posts publicados, luego itero esa lista para hacer una petición individual por cada post y traer el contenido principal. 

Para hacer las peticiones a Notion se puede usar cualquier cliente HTTP, pero yo decidí usar el SDK de notion, así que instale el paquete 

. La petición petición inicial queda así:

const Notion = require('@notionhq/client')

const notion = new Notion.Client({ auth: process.env.NOTION_PK })

const response = await notion.databases.query({
    database_id: process.env.NOTION_DB_ID,
    page_size: PAGE_SIZE,
    filter: {
      and: [
        {
          property: 'Status',
          select: {
            equals: 'publish'
          }
        },
        {
          property: 'Type',
          select: {
            equals: 'post'
          }
        }
      ]
    },
    sorts: [
      {
        property: 'Date',
        direction: 'descending'
      }
    ]
  })

Una vez que responde y tengo todos los post disponibles, itero la lista y hago la siguiente petición por cada item, con esto me traigo el contenido principal de cada post.

const postResponse = await notion.blocks.children.list({
  block_id: node.id,
})

const post = {
  id: node.id,
  title: node.properties.Content.title[0].plain_text,
  content: postResponse.results,
  createdAt: node.created_time,
  publishedAt: node.properties.Date.date.start,
  slug: node.properties.Slug?.rich_text[0].plain_text || node.id,
  permalink: node.properties.Permalink.url,
  tags: node.properties.Tags.multi_select.map(tag => tag.name.toLowerCase()),
  image, // <--- TODO: Download this image!!
}

Y listo, ya tengo todo la información. Simplemente creo un nuevo arreglo de posts con los fields que necesito y guardo el JSON en un archivo de texto para poder usarlo después.

Otro de los problemas es que tengo definidas imágenes para cada post, esta imagen la selecciono directamente en Notion, ya sea subiendo una que yo tenga en mi disco duro o bien usando el widget de UnSplash.

Estas imágenes son privadas, y el API de Notion te regresa la URL donde están almacenadas en Amazon S3. Pero, al ser privadas expiran en 30 minutos, así que es necesario descargarlas para que las puedas mostrar desde el servidor donde vas a deployar este sitio, en mi caso Github Pages.

Descargar imágenes o archivos en Node, no es complicado, yo lo hice de la siguiente manera:

Como se puede observer descargo las imágenes en el folder público del proyecto, cuando se hace el build, todos los archivos en este folder serán parte del resultado final, así que es importante poner las imágenes aquí para que pueda ser servidas cuando se deploye este sitio a producción.

Otro problema que me encontré es que las imágenes que vienen de UnSplash estás muy grandes, esto hace que el sitio se ponga lento en la carga inicial. Para optimizar esto es necesario redimensionar las imágenes para crear versiones más pequeñas.

Para redimensionar las imágenes, decidí usar una librería llamada 

, es bastante rápido y las imágenes quedan con buena calidad.

Una vez las imágenes ya estaban descargadas y redimensionadas, simplemente guardé la URL correcta en el JSON que tengo en mi local.

const remoteImage = node.cover?.type === 'external'
	? node.cover?.external?.url 
	: node.cover?.file?.url

if (remoteImage) {
  const sizes = [
    { name: 'tiny', width: 10 },
    { name: 'tns', width: 500 },
    { name: 'large', width: 1200 },
  ];
  const imageName = `${node.id}.${getImageFormat(node)}`

  await downloadImage(remoteImage, imageName)
  await resizeImageToMultipleSizes(imageName, sizes)

  image = {
    original: `/images/original/${imageName}`,
    large: `/images/large/${imageName}`,
    tns: `/images/tns/${imageName}`,
    tiny: `/images/tiny/${imageName}`,
  }
}

const post = {
  id: node.id,
  title: node.properties.Content.title[0].plain_text,
  content: postResponse.results,
  createdAt: node.created_time,
  publishedAt: node.properties.Date.date.start,
  slug: node.properties.Slug?.rich_text[0].plain_text || node.id,
  permalink: node.properties.Permalink.url,
  tags: node.properties.Tags.multi_select.map(tag => tag.name.toLowerCase()),
  image,
}

¡Listo! Eso es toda la integración con Notion, ya tenemos en nuestro local los posts, así como las imágenes de cada uno.

Como migrar de Wordpress a Notion

Al día de hoy JavaScript es el lenguaje más importante de la web, si vamos a GitHub (la red social de los desarrolladores) veremos que JavaScript es el 

 en los proyectos Open Source, superando a Ruby, Python, Java, PHP, etc.

Actualmente existen muchos servicios en la web hechos con PHP, Ruby, Java, .Net, Python, etc. del lado del servidor, pero todos ellos coinciden al usar JavaScript para el lado de las interfaces, no importa la tecnología que esté por detras todos ellos usan JavaScript para hacer Ajax, agregar interacción y mejorar la experiencia del usuario. Existen muchas librarías para desarrollar aplicaciones web, siendo 

 la más popular de todas por su facilidad y rapides para hacer las cosas, en lo personal yo usaría jQuery para sitios webs, portales sencillos, cosas pequeñas y medianes, jQuery es genial manejando el DOM, existe una gran comunidad detras de la librería e infinidad de plugins, pero cuando se trata de una aplicación grande para prefiero 

 ya que contiene una mejor arquitectura y muchos componentes listos para usarse ni siquiera 

 u otros plugins se asemejan al poder y flexibilidad que tenemos con Ext JS.

 es un excelente proyecto para llevar JavaScript del lado del servidor, tiene una excelente integración con WebSockets para lograr una comunicación permanente con el cliente y poder hacer "push" con información al cliente. Existen varios projectos como 

 que es un framework semejante a Sinatra para desarrollar aplicaciones de una manera ordenada y sencilla, Node.js utiliza el motor de Google Chrome llamado V8 para ejecutar y compilar el código JavaScript directamente en el servidor. Un proyecto muy prometedor y que vale la pena seguir de cerca.

El desarrollo para dispositivos móviles también es algo que ha evolucionado mucho, hoy en día existen herramientas que nos permiten desarrollar aplicaciones para móviles usando JavaScript, una de las ventajas de esto es que podemos escribirlas en JavaScript y compilarlas para diferentes plataformas usando Titanium por ejemplo o bien usar algún "wraper" como PhoneGap y desarrollar con 

. Ahora bien, varias personas me han llegado a preguntar si usar jQuery Mobile o Sencha Touch en sus proyectos, mi respuesta es simple, si quieres hacer algo sencillo como un sitio web o una app simple usa jQtouch, por el contrario si deseas hacer algo más completo y robusto utiliza Sencha Touch que esta pensado para aplicaciones más grandes.

Hay varios experimentos y pruebas de conceptos alrededor de JavaScript, uno de los últimos experimentos que me llamo mucho la atención fue una 

Java Virtual Machine corriendo en JavaScript

, aseguran que corre un 60% del bytecode! es algo realmente alucinante, no tengo palabras para expresar el asombro. También he visto otro experimento para 

 directamente desde JavaScript sin necesidad de plugins de terceros, suena muy interesante este proyecto. 

 es otro experimento muy interesante, permite interpretar texto por voz usando JavaScript y HTML5.

JavaScript era un lenguaje menospreciado hace algunos años, pero hoy en día es el más importante en la web y viene con mucha fuerza para los dispositivos móviles y el servidor, hoy es el momento ideal para subirse al barco y aprender estas tecnologías, esto apenas inicia así que no pierdas más el tiempo y 

The Blog

Latest Posts

Como migrar de Wordpress a Notion

Hoy es el momento ideal para aprender JavaScript

Connect with me!

Tags

You can follow me in these other places too.

I'm also on YouTube