Diego López

Desarrollador web, DJ y productor

Crear un blog con ficheros markdown

¿Por qué markdown? Porque me parece la forma más sencilla para mantener los artículos de un blog, cada artículo es un fichero .md en el proyecto y gracias a esto no necesitas bases de datos (como pasa en Wordpress), es lo que se conoce como JAMStack 🚧.

Lo bueno de markdown es que está soportado en todos los editores de texto y es una opción que está muy estandarizada. Además su sintaxis es muy sencilla, permitiendo añadir encabezados, listas, enlaces, imágenes e incluso tablas.

Ya te avanzo que para este artículo voy a usar Eleventy (la herramienta que uso para este blog), una opción perfecta si ya conoces HTML 🚧, CSS 🚧 y Javascript 🚧. Hay otras opciones para otros lenguajes como Jekyll (para Ruby), Hugo (para Golang), y Zola (para Rust). Otra opción muy interesante es Astro, aunque no lo he usado nunca. En esta página puedes ver todas las opciones que tienes para construir un sitio basado en JAMStack.

Lo que me mola de Eleventy 🚧 es que es muy sencillo, pero lo puedes ampliar y extender todo lo que quieras. Al estar basado en Javascript, si ya vienes del mundo Frontend 🚧 no tienes que aprender otro lenguaje.

Ventajas de este sistema

Lo más rápido: usando mi starter project

Si no te quieres complicar la vida lo más sencillo es coger un starter project, es decir, un proyecto que ya ha creado alguien y que está listo para desplegarse, tan solo tienes que configurar el nombre de tu sitio (o alguna información extra) y crear los artículos en ficheros markdown.

Para facilitarte la vida he creado un proyecto open source con un proyecto de Eleventy ya configurado y con un tema bastante elegante y minimalista, lo he llamado Nulite.

Captura de la web que se genera con el starter project. Se ven un par de artículos de ejemplo y una sección de topics con varios tags

Aquí el link del starter project

Para usarlo tan solo tienes que clickar en el botón de verde de "Use this template" y luego a "create new repository" para tener el código en tu propio repo, así puedes modificarlo (tienes que tener cuenta en Github). Por cierto, ya que estás si quieres dale star ⭐ al proyecto, que me mola saber que a la gente le mola lo que hago.

Lo primero que tienes que hacer es descargar tu repo en tu ordenador y luego desde la terminal ejecutar esto para instalar las dependencias:

npm install

Para arrancar la página tienes que ejecutar este comando:

npm run start

Hecho eso puedes abrir la página en tu local: http://localhost:8080

Cada vez que hagas un cambio en uno de los ficheros la página se refrescará automáticamente.

El comando para hacer el build (generar los ficheros html para subirlos a producción) es el siguiente:

npm run build

Sirviendo desde cualquier servidor o hosting la carpeta _site generada (por ejemplo mediante Nginx) será más que suficiente para desplegar tu página. Si no tienes hosting no te preocupes porque más abajo en este artículo explico varias opciones gratuitas (y no es publi).

Estructura de ficheros

Dentro de la carpeta src está todo el contenido que va a tener la web, y dentro del fichero eleventy.config.js es donde se configura Eleventy. Para este starter he metido el plugin de RSS y otro para tener coloreado de sintaxis por si quieres compartir código en algún artículo.

Lo primero que tienes que hacer es ir a src/_data/site,js y dentro cambiar la información y poner la tuya.

Dentro de src, cada fichero .liquid creará una página en tu blog, el nombre del fichero configura la ruta que tendrá, por lo que rss.liquid crea la ruta /rss, por eso tienes que crear los ficheros sin espacios, en minúsculas y usando guiones y no guiones bajos (por ejemplo /esto-es-una-pagina.liquid).

En la carpeta public están los assets, es decir, los ficheros estáticos que únicamente se copian en el proceso de build. Aquí es donde he puesto las imágenes del favicon (la pequeña imagen que se ve al lado de la pestaña de la web en el navegador).

Veamos cada ruta que contiene el template:

Dentro de la carpeta posts es donde están los artículos markdown. Si te mola el template tal como está simplemente tienes que añadir todos tus artículos aquí y subir a producción. Hay un par de artículos creados para que veas el funcionamiento, los puedes borrar o cambiar.

Dentro de cada artículo, al inicio, tienes que poner los metadatos del mismo, es decir, el título, descripción y tags, y debajo escribes el propio artículo. Fíjate en los artículos ya creados para que veas los metadatos a los que me refiero.

Por último está la carpeta _includes que contiene partes que he usado para crear el template, por ejemplo el navbar, footer, lista de posts, etc. Si sabes algo de HTML o CSS puedes cambiar aquí el aspecto de tu página. En layouts están los ficheros con la estructura de cada tipo de página.

Un fichero importante de esta carpeta es css/global.liquid. Este fichero contiene los estilos globales de la página. Dentro he creado una serie de variables CSS 🚧 que puedes tocar para cambiar los colores, fuentes, espaciado y demás tokens de diseño.

Y poco más, como ves es bastante simple. Te invito a que trastees con el blog para dejarlo a tu gusto. Si encuentras algún bug manda un issue a mi proyecto de Github, o si te animas a cambiar algo que sea de interés general manda PR.

Otras opciones: usar otros starters

Si no te mola mi starter project, lo bueno es que Eleventy tiene un montón de starters, creados por la comunidad. En esta página se listan todos los proyectos starters. Elige el que más te mole y dale a source code. Ya dentro del Github del proyecto lo que puedes hacer es un fork del proyecto (en algunos proyectos incluso sale un botón verde que pone Use this template), de tal forma que tengas el proyecto pero en tu propio repositorio (tienes que tener cuenta en Github).

Dependiendo del proyecto que hayas escogido la estructura de los ficheros puede cambiar un poco. Normalmente en el fichero README.md del proyecto puedes leer una descripción del mismo y a veces incluyen instrucciones de uso.

En estos proyectos suele ser común que exista una carpeta _data en la que se puede configurar determinados aspectos como el titulo del blog, su descripción, autor, idioma, etc, pero como digo depende de cómo se haya hecho el proyecto starter.

En estos proyectos habitualmente los artículos los suelen meter dentro de src, content, pages o nombres similares. Lo que tienes que hacer es localizar dónde se encuentran los ficheros .md del proyecto, ya que va a ser ahí donde tengas que crear los tuyos.

La última opción: crearlo desde cero

Esta es la opción más lenta, pero también la más satisfactoria, ya que por el camino seguro que aprendes algo.

Consiste en crear un repo vacío, instalar eleventy y poner el comando de build del proyecto dentro del package.json. Luego creas el fichero eleventy.config.js y lo configuras a tu gusto. Por último construyes el sitio a tu gusto.

Lo bueno de esta opción es que vas a poder personalizar todo mucho más fácil. Como tú mismo has montado el proyecto, sabes dónde tocar si quieres cambiar algo. Además aprendes a usar Eleventy, que te puede servir para crear otras páginas estáticas como landings, portfolios, etc.

Lo malo es que te vas a tirar varios días (o semanas) haciendo el proyecto y no vas a poder tenerlo desplegado en poco tiempo.

Hosting gratis

Y no es publicidad de ningún proveedor, son literalmente los dos hostings que uso para alojar mi blog. Para esta clase de blogs estáticos yo recomiendo Vercel y Netlify. Ambos son muy parecidos, Netlify lo usaba antes para mi blog pero lo migré a Vercel porque Netlify no permite repos privados.

Por ejemplo veamos cómo se hace en Netlify. Tras iniciar sesión con Github le voy a dar a "Import from Git" y luego "Deploy from Github" para que tenga acceso al repo, en este caso voy a seleccionar el repo del template.

Captura de pantalla de Neltify en la que se ve el botón de Import from Git

Tras darle permisos a mi cuenta de Github y seleccionar el repo deberías ver una pantalla como esta. Como ves todos los campos ya aparecen rellenos. Netlify ha detectado que se trata de un proyecto Eleventy y ha configurado el comando de npm run build y la carpeta _site que usará para servir los ficheros. En principio solo tienes que darle a deploy.

Pantalla de configuración del proyecto de Netlify con los campos rellenos por defecto

¡Y listo! Tu blog ya está en Internet. Lo que pasa es que netlify por defecto ha generado una URL única que es un poco fea

Captura de Netlify en la que se puede leer la url que empieza por fastidious-crostata-230afb

Puedes irte al botón de "Site configuration" y luego a "Change site name" para que puedas poner un nombre que mole más. En mi caso he puesto https://nulite-starter.netlify.app/.

Como ves el dominio termina en netlify.app, esto es porque es un dominio gratis de netlify. Si quieres tu propio dominio vas a tener que pagar, te puede costar desde 4 o 5 euros al año a miles de euros, dependiendo de qué dominio sea. Si ya tienes un dominio configurado puedes vincularlo con Netlify para que apunte a tu blog, yo es lo que tengo hecho, solo pago el dominio de mi web.

Lo que mola es que ya tienes configurado los deploys automáticos, cada vez que hagas commit en la rama main/master de tu proyecto se lanzará el build para que los cambios se vean en la web desplegada.

En Vercel el proceso es muy similar. Te registras usando la cuenta de Github y creas un nuevo proyecto. A la hora de configurarlo comprueba que el comando de build sea npm run build y que la carpeta servir sea _site. En Vercel también te asignaran un dominio .vercel.app que puedes cambiar si tienes un dominio comprado.