Creando un sitio web estático con Jekyll y GitHub

En este artículo voy a mostrar paso a paso cómo crear un sitio web estático con Jekyll desde un equipo con Windows 11 y cómo alojarlo en un repositorio de GitHub. No me voy a extender mucho en el uso de Jekyll, para ello he adjuntado unos enlaces de interés a la documentación oficial; me centraré en la creación del sitio y el correspondiente despliegue en GitHub.

Objetivo

Crear un sitio estático, comprobarlo en local y publicarlo mediante GitHub Pages con un dominio propio opcional.

Las capturas de instalación corresponden a Windows 11 en 2023. Las versiones que aparecen en ellas son una referencia del laboratorio. Para un proyecto existente, utiliza la versión de Ruby indicada por el proyecto y sus dependencias bloqueadas.

Arquitectura, cómo trabajar con Jekyll y GitHub

Jekyll permite ejecutar nuestro sitio estático en un servidor local http://localhost:4000. Esto nos permite revisar los cambios que aplicamos en el repositorio local en nuestro equipo antes de aplicar un commit o un push al repositorio público.

Por lo tanto el repositorio local lo trato como entorno de desarrollo y el público como producción.

Una vez realizado un push al repositorio público se ejecuta automáticamente un workflow de GitHub Actions que despliega el sitio de Jekyll en GitHub Pages.

Prerrequisitos

Necesitas una cuenta de GitHub, Git instalado y Ruby con sus herramientas de compilación. En Windows, sigue la instalación oficial de Jekyll mediante RubyInstaller, seleccionando una versión Ruby+Devkit compatible con el proyecto desde RubyInstaller. Windows requiere los ajustes descritos en esa documentación.

Durante la instalación nos aseguramos tener marcadas las siguientes dos opciones:

• Add Ruby executables to your PATH.
• Associate .rb and .rbw files with this Ruby installation.

En las capturas originales seleccioné estos componentes; las versiones disponibles ahora pueden ser distintas:

• Ruby-3.2.2 base files.
• Ruby RI and HTML documentation.
• MSYS2 development toolchain 2023-04-01.

Tras finalizar la instalación dejamos marcado “Run ridk install” para que arranque la instalación de MSYS2 y las herramientas de desarrollo.

Por último tenemos que instalar el componente 3 - MSYS2 and MINGW development toochain.

Instalar Jekyll

Los comandos que facilito a continuación se ejecutan desde una consola CMD.

Lo primero que tenemos que hacer es instalar Jekyll:

gem install jekyll bundler

El siguiente comando sirve para comprobar la versión de Jekyll instalada:

jekyll -v

Para crear un nuevo blog o sitio estático ejecutamos el siguiente comando:

jekyll new myblog

Para arrancar el servidor local de Jekyll y visualizar el blog accedemos a la carpeta myblog, instalamos las dependencias y ejecutamos:

cd myblog
bundle install

bundle exec jekyll serve

Abrimos en el navegador la siguiente URL http://localhost:4000 y podremos visualizar el blog.

Enlaces de interés Jekyll

Para que puedas ampliar conocimientos sobre el uso de Jekyll te facilito una serie de recursos de la documentación oficial que te ayudarán a entender la estructura de directorios, creación de contenido, plugins y temas, entre otros.

Contenido

1. Pages
2. Post
3. Front Matter
4. Collections
5. Data Files
6. Assets
7. Static Files
8. Plugins

Estructura del sitio

1. Structure
2. Liquid
3. Variables
4. Includes
5. Layouts
6. Permalinks
7. Themes
8. Pagination

Publicar sitio en GitHub

Para publicar nuestro sitio estático en GitHub seguimos los siguientes pasos:

1. Crear un repositorio en GitHub.

   

2. Clonamos nuestro repositorio en un directorio local de nuestro equipo. Yo hago uso de Visual Studio Code, pero también existen otras herramientas que facilitan la gestión de repositorios de GitHub como GitHub Desktop.

3. Copiamos el contenido de nuestro sitio al repositorio clonado.

4. Hacemos commit de todos los cambios y posteriormente un push para que se suba el contenido al repositorio público.

   

Desplegar sitio en GitHub Pages

Una vez tenemos nuestro sitio público en GitHub tenemos que configurar GitHub Pages para que muestre el sitio web en un dominio de GitHub. Para ello vamos a Settings > Pages desde el repositorio público.

En source seleccionamos GitHub Actions.

Seleccionamos configurar Jekyll.

Por último hacemos commit para aplicar el workflow que GitHub Actions nos facilita para el despliegue del sitio de Jekyll en GitHub Pages.

Configurar un dominio personalizado

Un sitio de usuario utiliza https://[usuarioGitHub].github.io/; un sitio de proyecto suele añadir /[repositorio]/. Configura url y baseurl de Jekyll según el destino.

Antes de tocar el DNS, verifica la propiedad del dominio y añádelo en Settings > Pages > Custom domain. Después configura los registros de tu proveedor, siguiendo la documentación oficial de dominios personalizados. Para un dominio raíz, los registros del ejemplo son:

Crear los siguientes registros A:

   185.199.108.153
   185.199.109.153
   185.199.110.153
   185.199.111.153

Crear los siguientes registros AAAA:

   2606:50c0:8000::153
   2606:50c0:8001::153
   2606:50c0:8002::153
   2606:50c0:8003::153

Crear un registro CNAME en la que el subdominio sea www y el destino [usuarioGitHub].github.io.

Comprueba el dominio que has guardado en Settings > Pages y activa Enforce HTTPS cuando esté disponible.

Tras validar el dominio personalizado el sitio web estará en marcha.

Verificación final

Antes de publicar, ejecuta bundle exec jekyll build y corrige los errores. En local revisa navegación, imágenes y enlaces con el baseurl real. Tras el despliegue, comprueba que GitHub Actions termina correctamente, que la URL pública carga por HTTPS y que las rutas internas funcionan sin pasar por la portada.

Conclusión

En este artículo has visto cómo levantar un blog con Jekyll desde cero, publicarlo en GitHub y desplegarlo automáticamente en GitHub Pages, incluyendo la configuración de un dominio personalizado.

GitHub Pages permite alojar sitios estáticos de repositorios públicos con GitHub Free. Revisa los límites y las condiciones del plan que uses; registrar un dominio propio tiene su coste independiente.

Si tienes alguna duda sobre alguno de los pasos o quieres compartir cómo has personalizado tu propio sitio, déjame un comentario.