Cómo crear un blog en Jekyll

A diferencia de los motores de blogs o CMS como Wordpress o Ghost, el resultado final de Jekyll no son programas ejecutables en un lenguaje de programación, sino archivos HTML estáticos. Por lo tanto, no necesitas PHP, Node, bases de datos ni un hosting potente para alojar el sitio. La entrega de archivos estáticos genera una carga mínima en el servidor, por lo que generalmente es suficiente con un hosting económico.

Puedes alojar un sitio de Jekyll de forma gratuita en Github Pages, y eso es lo que haremos en esta guía.

Resumen

Veamos brevemente cómo funciona Jekyll y cómo publicar un sitio.

1. Creas plantillas para tu sitio, es decir, cómo se ve la página principal, cómo se ven las páginas de publicaciones, categorías, encabezados, pies de página y otros bloques del sitio.
2. Escribes publicaciones en formato Markdown (también se admiten otros formatos).
3. Jekyll genera las páginas HTML finales basadas en las plantillas y los archivos Markdown.
4. Publicas los archivos HTML en un servidor web y el sitio se vuelve accesible en Internet.

GitHub Pages te permite alojar cualquier página HTML, pero también admite Jekyll en su lado. Esto significa que no necesitas enviar el HTML generado a Github, solo envía la carpeta de tu proyecto de Jekyll y los archivos Markdown, y Github generará el HTML y lo alojará por ti.

Instalación de Jekyll en tu máquina local

Hay dos formas de trabajar con Jekyll en tu máquina local, directamente o a través de Docker. La segunda forma es más fácil y rápida, pero puede ser desconocida si nunca has trabajado con Docker antes.

Instalación y ejecución directa de Jekyll

Jekyll es un programa de línea de comandos escrito en Ruby. No necesitas conocer este lenguaje para trabajar con Jekyll, pero debes tener el intérprete de Ruby instalado en tu sistema.

Dependiendo del sistema operativo, es posible que ya tengas Ruby instalado.

En Windows, puedes usar RubyInstaller. Debes trabajar con Jekyll a través de la línea de comandos.
La documentación oficial de Jekyll tiene una sección dedicada a diferentes formas de instalar Ruby y Jekyll en Windows.

En macOS y Linux, verifica si Ruby está instalado y qué versión tienes (la documentación oficial de instalación de Jekyll tiene una guía para cada sistema operativo).

ruby -v
ruby 3.x.x (...)

Jekyll 4.4.1 necesita Ruby 2.7.0 o superior. Si no tienes Ruby, o la versión es anterior, instala una reciente con Homebrew (brew install ruby) o con un gestor de versiones como rbenv o asdf (puedes leer más en la guía qué es un gestor de versiones). No uses el comando sudo gem install ruby, porque Ruby no es una gema y ese comando no actualiza el intérprete.
Ahora, instala Bundler. Es un administrador de paquetes que te permitirá instalar Jekyll y otros paquetes necesarios.

gem install bundler

Luego, instala Jekyll.

gem install jekyll

Ahora, crea un blog.

jekyll new myblog
cd myblog
bundle exec jekyll serve

Abre tu navegador.

Instalación y ejecución de Jekyll a través de Docker

La imagen de Docker de Jekyll es jekyll/jekyll. Los comandos exactos para compilar y servir el sitio con esta imagen están en el README del proyecto jekyll-docker. Consúltalo allí, porque las imágenes y sus etiquetas cambian con el tiempo (por ejemplo, las imágenes jekyll/builder y jekyll/minimal ya no se publican).

La forma más sencilla de comenzar es utilizar nuestro paquete con un tema predefinido basado en Bootstrap 4. Ten en cuenta que Bootstrap 4 llegó al fin de su vida útil y ya no recibe actualizaciones, así que este paquete sirve como ejemplo para aprender. En un proyecto propio conviene usar una versión vigente de Bootstrap o el tema que trae Jekyll por defecto.

git clone git@github.com:hexlet-boilerplates/jekyll-bootstrap4-docker.git
cd jekyll-bootstrap4-docker
make serve

Abre tu navegador.

Estructura de archivos

La estructura básica de un directorio de un sitio se ve así.

.
├── _config.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.md
|   └── on-simplicity-in-technology.md
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-hello.md
|   └── 2009-04-26-good-stuff.md
├── _sass
|   ├── _base.scss
|   └── _layout.scss
├── _site
└── index.html

En resumen.

• tus publicaciones (por ejemplo, en formato Markdown se encuentran en la carpeta _posts
• las plantillas de las páginas se encuentran en la carpeta _layouts
• los bloques repetitivos utilizados en las plantillas se encuentran en la carpeta _includes
• la página principal del sitio se encuentra en index.html

Jekyll toma una plantilla como base, genera páginas HTML finales para cada publicación y recopila todo el sitio en la carpeta _site.

Configuración

_config.yml

El archivo _config.yml contiene la configuración del sitio.

title:       "Page title"
header_title: "Header Title"
email:       your@ema.il
author:      Your Name
description: "My blog description"
baseurl:     ""
url:         "https://myblog.com"
date_format: "%-d.%m.%Y"

Un detalle importante es que url es la dirección de tu sitio raíz, y baseurl es la ruta de tu sitio de Jekyll.

https://hello.goo.com/myblog/
|--------------------|======|
         |              |
        url          baseurl

Si tu sitio está en la raíz, baseurl estará vacío.

Además de los parámetros básicos, puedes agregar tus propios parámetros en este archivo. Estarán disponibles en las plantillas. Por ejemplo, puedes agregar una línea en la configuración con tu usuario de GitHub.

github_username: example

Este parámetro se utiliza en el archivo _includes/header.html.

{% raw %}{% if site.github_username %}
  <li class="nav-item">
    <a class="nav-link" href="https://github.com/{{ site.github_username }}">
      <span class="mr-1 fa fa-github"></span>
    </a>
  </li>
{% endif %}{% endraw %}

Aquí se dice "si hay un parámetro github_username en la configuración con un valor no vacío, muestra un enlace a GitHub".

Configuración del tema

Jekyll viene con un tema base. Nuestro paquete se basa en el popular framework Bootstrap 4.

Veamos más de cerca nuestro ejemplo.

• _includes contiene bloques utilizados en varios lugares

• head.html es el elemento <head>, donde se incluyen los estilos, las etiquetas meta, etc.

• header.html es el encabezado del sitio

• footer.html es el pie de página del sitio

• post_footer.html se muestra debajo de una publicación en la página de la publicación (se incluye en la configuración)

• share_buttons.html son los botones de compartir en redes sociales debajo de una publicación en la página de la publicación (se incluyen y se configuran en la configuración)

• social_links.html son los enlaces a redes sociales que se muestran en el encabezado del sitio (se incluyen y se configuran en la configuración)

• _layouts contiene las plantillas principales del sitio

• default.html es la plantilla principal, se utiliza en la página principal

• post.html es la plantilla de una publicación, se utiliza en la página de la publicación

• css contiene los estilos

• style.css es el archivo principal de estilos del sitio

• likely.css son los estilos para los botones de compartir en redes sociales

• js contiene los scripts

• likely.js es el script para los botones de compartir en redes sociales

• images contiene las imágenes

Front Matter

Cualquier archivo que contenga un bloque Front Matter en formato YAML será procesado por Jekyll como un archivo especial. El bloque Front Matter debe ir al comienzo del archivo.

Por ejemplo, la página index.html (página principal del sitio) contiene estas líneas al comienzo.

---
layout: default
---

Y así se ve la plantilla predeterminada (archivo _layouts/default.html).

{% raw %}<!DOCTYPE html>
<html>
{% include head.html %}
<body>
  {% include header.html %}
  <div class="container">
    <div class="row">
      <div class="col">{{ content }}</div>
    </div>
    {% include footer.html %}
  </div>
</body>
</html>{% endraw %}

De esta manera, Jekyll toma el contenido del archivo index.html, lo inserta en {% raw %}{{ content }}{% endraw %} de la plantilla y crea el archivo index.html final.

Creación de publicaciones

Las publicaciones se encuentran en la carpeta _posts. Utilizamos el formato predeterminado, Markdown. Un ejemplo de nombre de archivo es 2017-12-18-features.md. Como puedes ver, la fecha de publicación se incluye en el nombre del archivo. Después de la fecha, viene el título que se utilizará en la URL. Esta publicación estará disponible en mysite.com/features.

La publicación también comienza con un bloque front matter.

---
layout: post
title: Features
cover_url: "/images/tree.jpg"
---

Aquí puedes incluir tanto variables de Jekyll como tus propias variables. En este caso, hemos incluido dos variables personalizadas, title y cover_url. Se utilizan en las plantillas.

Esto se ve en el archivo _layouts/post.html.

<h1>{% raw %}{{ page.title }}{% endraw %}</h1>

Y esto en el archivo _includes/head.html.

<meta property="og:image" content="{{ page.cover_url | prepend: site.baseurl | prepend: site.url }}">

Aquí se establece la URL completa de la imagen de portada para las redes sociales.

Puedes colocar imágenes en cualquier directorio y usarlas en las publicaciones y en el Front Matter utilizando rutas relativas.

Creación de páginas

Puedes crear cualquier directorio y archivo HTML por tu cuenta, siguiendo el ejemplo de index.html.

Por ejemplo, si creas el directorio works y colocas un nuevo archivo index.html dentro (que incluso puede no contener front matter y ser un archivo estático independiente), la página estará disponible en mysite.com/works (según los valores de url y baseurl en la configuración).

Publicación en Internet

Publicación de archivos HTML en un servidor web

Simplemente coloca los archivos de la carpeta _site en un servidor web. Casi cualquier hosting servirá para esto.

Publicación en Github Pages con soporte para Jekyll

Github, un popular hosting de repositorios git, admite Jekyll. Esto significa que puedes colocar toda la carpeta de tu proyecto de Jekyll en un repositorio, y Github generará el HTML por ti. No necesitas incluir la carpeta _site en el repositorio. Los archivos HTML finales no se mostrarán en el repositorio de ninguna manera. Este servicio se llama Github Pages.

1. Regístrate en https://github.com/ si aún no lo has hecho.
2. Crea un nuevo repositorio con el nombre username.github.io, donde username es tu nombre de usuario en Github.
3. Inicializa el repositorio en el directorio de Jekyll con git init
4. Agrega el remote con git remote add origin git@github.com:YOUR_USERNAME/YOUR_REPO.git
5. Haz un commit y envíalo a Github (la rama principal de los repositorios nuevos se llama main). Ejecuta git add --all, git commit -m "Initial commit", git branch -M main y git push -u origin main
6. Después de unos momentos, tu página estará disponible en tu dirección

Esta es una forma conveniente de trabajar, pero como la compilación se realiza en el lado de Github, no puedes controlar este proceso. Por ejemplo, no puedes instalar ningún plugin, ya que Github solo admite un conjunto limitado de plugins básicos. Además, GitHub Pages compila con su propia versión de Jekyll (3.10.0 a la fecha de esta revisión), que puede ser más antigua que la que instalas en tu máquina. Por eso, hoy GitHub recomienda publicar con GitHub Actions, un flujo de trabajo propio que te da más control sobre la compilación. Puedes leer más en la documentación de GitHub Pages y Jekyll.

Publicación en Github Pages sin soporte para Jekyll

Github Pages te permite alojar cualquier archivo HTML y no trabajar con Jekyll en el lado de Github. Esto significa que simplemente puedes colocar tu carpeta _site en Github. Este enfoque te permite utilizar cualquier plugin, ya que la generación de archivos HTML se realiza en tu propia computadora y Github actúa como un servidor web simple.

El proceso es el mismo, solo debes almacenar los archivos HTML finales en el repositorio en lugar del proyecto de Jekyll.

Obtén más información sobre todas las opciones de alojamiento de sitios web en la página pages.github.com.

Conexión de tu propio dominio

Github Pages te permite conectar un dominio personalizado. Además, se realizará una redirección 301 automática desde la dirección https://YOUR_USERNAME.github.io a tu dominio.

1. Si publicas desde una rama, agrega un archivo CNAME (sin extensión) a tu repositorio y escribe tu dominio sin el protocolo. Por ejemplo, myblog.com. GitHub lo crea por ti cuando guardas el dominio en la configuración del repositorio. Si publicas con un flujo de trabajo de GitHub Actions, este archivo no se crea y no hace falta.
2. Si estás utilizando un dominio de segundo nivel, configura un registro ALIAS o ANAME en tu proveedor de DNS con el valor YOUR_USERNAME.github.io; o configura cuatro registros A con los valores 185.199.108.153, 185.199.109.153, 185.199.110.153 y 185.199.111.153 (GitHub también ofrece registros AAAA para IPv6, consulta la documentación). Si estás utilizando un dominio de tercer nivel, configura un registro CNAME con el valor YOUR_USERNAME.github.io. Obtén más información sobre tus dominios en la documentación oficial.

Funcionalidades adicionales

Todo lo descrito en esta guía se refiere a las funcionalidades y configuraciones básicas. La documentación oficial describe muchas funcionalidades adicionales, por ejemplo las siguientes.

• creación de "colecciones" de publicaciones y páginas
• paginación
• migración desde otras plataformas de blogs
• resaltado de código y soporte para fórmulas matemáticas en las publicaciones
• plugins
• temas
• etiquetas
• análisis de archivos de datos (YAML, JSON, CSV)
• integración continua

Los plugins te permiten ampliar aún más las funcionalidades del sistema.