Jekyll

Publicado el 17/02/2026

#jekyll #CMS

1. Instalación y primera entrada en Jekyll

Antes que nada, este sitio está construido con Jekyll. Como comento un poco en esta entrada, necesitaba un sitio que fuera de fácil mantenimiento. Esto incluye no estar actualizando librerías constantemente, tener la posibilidad de subir escritos rápido y modificar la estructura (secciones) o los valores de cada entrada (tags, categorías, descripciones, etc.) hasta encontrar la que mejor se ajuste. También buscaba que sea lo más permisivo posible: poca configuración y completa libertad para diseñar.

Cada sitio tiene su lógica y, probablemente, para la mayoría de los proyectos que programes no te sea de utilidad esta herramienta. No deja de sentirse como un CMS a medio camino. Seamos honestos: si bien menciono que es una herramienta simple, lo es para para vos y para mí que podemos entender cómo escribir en Markdown, hacer un commit y un push a GitHub. Para la mayoría, en especial usuarios que buscan crear su blog y no saben programar, hay alternativas más amigables como Tina.io o WordPress que resultan mejores opciones.

¿Qué es?

Jekyll es una herramienta que transforma archivos Markdown en HTML. Pero no se queda solo ahí, sino que genera un sitio estático que nos permite organizarlo en distintas colecciones, configurar el estilo de cada entrada (fecha, imagen, descripción, orden) y manejar Liquid (lenguaje que conecta los archivos markdown con los archivos html) para diseñar el sitio a medida.

Si armaste sitios personales en el pasado, probablemente te topaste con tres enfoques:

  • Completamente estáticos: Cada actualización implicaba crear un HTML manualmente y listarlo en una página indexadora.
  • Semidinámicos: Usando un archivo JSON donde escribías las entradas para que luego el sitio, mediante JavaScript, las consumiera e “hidratara” la página.
  • Automáticos: Con una base de datos y un panel dedicado a la creación de contenido.

Jekyll toma lo mejor de estos mundos:

  • Genera una página estática, lo que la hace extremadamente rápida.
  • Es semiautomática: no escribimos en JSON, sino en Markdown, y el motor los convierte a HTML.
  • Es automático en su despliegue: no usamos base de datos, sino que utilizamos el mismo repositorio de GitHub como contenedor. Todo se guarda allí y, al desplegar, el sitio se construye tomando esos archivos.

Instalación

Jekyll utiliza Ruby, RubyGems, GCC y Make.

En Windows, lo ideal es descargar el RubyInstaller y luego, desde la terminal, ejecutar:

gem install jekyll bundler

En Linux, abrimos la terminal e instalamos las dependencias:

sudo apt-get install ruby-full build-essential zlib1g-dev

Luego, configuramos las variables de entorno en el .bashrc para evitar problemas de permisos con las gemas:

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Y finalmente instalamos Jekyll:

gem install jekyll bundler

Creando el sitio

Ahora tenemos que crear el proyecto o el sitio en el que vamos a trabajar. Desde la terminal, ejecutamos:

jekyll new sitio_nuevo

Ingresamos a la carpeta raíz y levantamos el servidor en http://localhost:4000:

bundle exec jekyll serve

Podemos usar la bandera --livereload para que el sitio se reconstruya automáticamente con cada cambio.

bundle exec jekyll serve --livereload

Si no ves los cambios, usá Ctrl + F5 para limpiar la caché del navegador.

Organización de archivos

Al crarse el proyecto, por defecto, la estructura que encontramos es la siguiente:

├── _config.yml          # Configuración principal.
├── _posts               # Entradas del blog.
│   └── 2026-02-17-bienvenido.md
├── _site                # Sitio generado (NO tocar, se recrea solo).
├── .jekyll-cache        # Caché de compilación.
├── about.markdown       # Página estática de ejemplo.
├── index.markdown       # Página principal.
├── Gemfile              # Dependencias de Ruby.
└── Gemfile.lock         # Versiones exactas de las gemas.

Las carpetas que comienzan con guion bajo (_) tienen un significado especial:

  • _posts: Aquí se procesan los archivos para generar URLs con fecha. El archivo 2026-02-17-bienvenido.md se convertirá en /2026/02/17/bienvenido.html.
  • _site: Es el resultado final. No debe modificarse manualmente.

Otras carpetas útiles que podés crear:

  • assets: Para imágenes, JS o CSS (sin el guion bajo es lo estándar para archivos públicos).
  • _includes: Fragmentos de HTML reutilizables (footer.html, navbar.html).
  • _layouts: Plantillas maestras (post.html, page.html).

Primera entrada

Ahora sí, podemos comenzar a crear nuestra primera entrada. Jekyll espera que los documentos en _posts sigan el formato año-mes-dia-titulo.md. Creamos el archivo, escribimos el contenido y, al guardar, verás la nueva entrada generada automáticamente como un archivo HTML. Ya está. Bastante simple. Pero quizás también querés darle tu propio estilo al sitio.

Mejorando el diseño

Para poder comenzar a darle estilo al sitio, lo primero que podemos hacer es crear una carpeta llamada /assets/ y subdividirla en /images/, /css/ y /js/. En cada una de estas carpetas es donde pondremos tanto imágnes del sitio, como los estilos (styles.css) o funcionalidades que queremos que tenga (scripts.js).

Vamos a necesitar crear un archivo index.html que vamos poder maqueater con total libertad. Y para que Jekyll lo reconozca como la página de inicio, podés configurar el permalink en el bloque superior (el cual se llama Front Matter):

---
permalink: "/"
---

El permalink es la regla que define la URL. Es el puente entre el archivo físico y la dirección en el navegador. Podés poner el permalink en cada página o podés cambiar el comportamiento global en el _config.yml. Esto nos permite podemos colocar todas las páginas que vayamos creando en una carpeta llamada pages para tener un mejor orden.

_config.yml

Este archivo es el mapa que lee Jekyll para construir el sitio. ¿Qué podemos hacer? Por ejemplo, si querés que tus posts no incluyan la fecha en la URL, agregá:

permalink: /posts/:title

Aquí :title es una variable que toma el nombre del archivo sin la fecha. También existen otras como :categories, la cual lee la categoría del archivo, o :slug, que toma el nombre del archivo y le quita espacios.

Colecciones

Ahora, supongamso que nuestro sitio tiene otras secciones como Fotografías o Dibujos que queremos separar de los posts, para esto podés usar Collections. Las colecciones es la manera en la vamos a agrupar las diversas entradas que tengamos en el sitio. Esto nos va a permitir darle a cada colección su propia lógica y manejo de datos. Por ejemplo, podemos tener en fotografía el link de la imagen, la cámara que se usó, el objetivo y diafragma seteado. Esto lo decidís vos. En Dibujo, en cambio, podríamos tener la técnica utilizada, el tiempo que nos llevó realizarlo, etc. Si tuviéramos otra colección llamada Libros en la que queremos dar una reseña del mismo, podŕiamos tener: título, autor, páginas, puntaje, etc.

Esto va a tener más sentido cuando comencemos a ver un poco de Liquid u Front Matter.

Esto se registra en el _config.yml:

collections:
  fotografias:
    output: true
    permalink: /fotografias/:path
  dibujos:
    output: true
    permalink: /dibujos/:path

Luego creás las carpetas correspondientes para cada colección (_fotografias, _dibujos). Jekyll entiende que cada colección corresponde a esas carpetas por el nombre que le pongamos. La opción output: true indica que cada archivo debe generar su propia página HTML.

Ahora necesitamos una página que contenga todas las entradas de cada colección, una especie de página índice en la que el usuario pueda seleccionar cuál quiere leer. Para listar estas colecciones usamos Liquid, el motor que actúa como puente entre tus datos y el HTML. Por ejemplo, en un archivo fotografias.html podrías poner:

<ul>
  {% for fotografia in site.fotografias %}
    <li>
      <a href="{{ fotografia.url }}">{{ fotografia.title }}</a>
    </li>
  {% endfor %}
</ul>

En site.fotografias están todos los documentos de esa colección fotografias (y en site están todos los documentos creados). Usamos el bloque {% %} para las estructuras. En este caso lo usamos para recorrer cada una de las entradas de la esa colección. El bloque {{ }} se lo utiliza para leer los valos que hay en cada archivo o variables.

En la siguiente parte veremos qué es el Front Matter y profundizaremos en Liquid.

¡Saludos!