A pedido del público, hoy voy a hacer un tutorial de cómo hacer un blog como este mismo.
(Actualizado el 01-04-2023: Probando la configuración y Estilos)
La herramienta que uso se llama Jekyll y está hecha en lenguaje Ruby.
El código lo subo a GitHub, que es un almacenamiento en la nube para repositorios Git. Un repositorio git es básicamente una base de datos en directorios que guarda distintas versiones del código. Otro día hago un post sobre git.
Github tiene un hosting gratuito para páginas que se llama GitHub Pages. Puede correr código hecho en HTML simple, en frameworks como React, o Jekyll, su motor incorporado de plantillas.
Lo interesante que tiene Jekyll es que, en teoría, se puede levantar un sitio con sólo un par de comandos.
Instalando Jekyll
Primero que nada tenemos que instalar Ruby.
Chequeamos si ya lo tenemos con ruby -v.
Si no, lo instalamos con un installer (Windows) o usando nuestro gestor de paquetes (brew en macOS, apt-get
para Debian/Ubuntu, pacman para Arch Linux, etc). Las instrucciones están en este link.
Después tenemos que instalar Bundler, una herramienta que nos ayuda a instalar “gemas” (las librerías de Ruby). Teniendo Ruby instalado, basta con correr el siguiente comando:
gem install bundler
Después instalamos Jekyll propiamente dicho:
gem install jekyll
Preparando el repositorio
Lo próximo que hay que tener instalado es git. Igual que Ruby, hay installers para windows,
o se lo puede bajar desde brew, apt-get o pacman (etc).
Desde la página de GitHub podemos crear un repositorio nuevo (antes hay que crearse un usuario, eso queda como ejercicio para el lector). En la esquina superior derecha, al lado de nuestra imagen de perfil, hay un signo +, y en el menú que se despliega hay que elegir “New repository”.
Elegimos un nombre para el repositorio (se va ver en la URL del blog) y le ponemos una descripción.
NOTA: si querés hacer un blog personal también podés crear un repositorio que se llame mi-usuario.github.io. En ese caso la configuración es más fácil y el blog va a estar directamente en la URL https://mi-usuario.github.io.
***
Opcionalmente se puede agregar:
- un README.md, archivo que explica de qué trata el repositorio a la gente que lee el código
- un .gitignore, archivo donde se lista lo que no queremos sincronizar con el repositorio (cache, por ejemplo)
- una licencia, para indicar a quienes usen nuestro repositorio qué derechos tienen (compartir, modificar, etc)
Yo en este caso elegí la licencia de Mozilla y un README.md.
Después tenemos que clonar (descargar) el repositorio en nuestra máquina. Hay tres opciones: HTTPS (requiere contraseña o personal access token), SSH (requiere una clave SSH registrada), GitHub CLI (tiene que estar instalado pero permite loguearse desde el navegador) o simplemente bajar un ZIP.
Yo voy a clonarlo con SSH. Configurarlo es una larga historia para otro día.
Para clonarlo hay que abrir una terminal en el directorio donde queremos guardarlo y ejecutar el siguiente comando:
git clone <dirección copiada de GH>
Esta es mi salida:
$ git clone git@github.com:mokocchi/jekyll-demo.git
Cloning into 'jekyll-demo'...
remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 4 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (4/4), 5.86 KiB | 5.86 MiB/s, done.
Cambiamos al directorio de nuestro repositorio:
cd <repositorio>
y creamos un directorio que se llame docs:
mkdir docs
Cambiamos al directorio docs:
cd docs
Creando el proyecto
Cambiamos con git a una rama gh-docs:
git checkout -b gh-pages
Y ahora, sí, creamos el proyecto:
jekyll new --skip-bundle .
El argumento --skip-bundle saltea la instalación, solo genera los archivos
(porque va a correr en el servidor de GitHub).
Si por alguna razón no pueden instalar Jekyll, pueden partir de los archivos en la rama jekyll-config de mi repositorio jekyll-demo copiando la carpeta docs:
git clone <link de mi repositorio copiado de GitHub>
cd jekyll-demo
git checkout jekyll-config
Configuración de Jekyll
Hay dos archivos para editar:
Gemfile: hay que comentar (poniendo un#al inicio de la línea) o borrar la línea que dicegem "jekyll"..., agregar esta línea:gem "github-pages", "~> 225", group: :jekyll_pluginsy bajo
group :jekyll_plugins doagregar esta línea:gem "jekyll-paginate"_config.yml: hay que editar los campos entre picos
NOTA: si estás creando un blog personal, baseurl es /
title: <titulo del blog>
email: <tu mail>
description: >-
<Una descripción
de varias líneas
acerca de tu blog.>
baseurl: "/tu-repositorio"
domain: tu-usuario.github.io
url: "http://tu-usuario.github.io/"
twitter_username: <tu twitter>
github_username: <tu github>
paginate: 5
paginate_path: "/page:num/"
show_excerpts: true
theme: <tu tema elegido>
plugins:
- jekyll-feed
- jekyll-paginate
El tema por defecto es minima, pero yo uso slate.
Layouts
Se pueden sacar layouts (diseños de página) de los repositorios de minima, slate, etc.
Yo me basé en los de minima, que es para blogs (hay otros temas como slate que son para páginas).
Hay que crear una carpeta _layouts dentro de docs. Estos layouts van a ser referenciados desde las páginas y posts usando el Front Matter (un pedazo de código YAML que sirve de metadatos) y están escritos en un lenguaje de plantillas que se apoya sobre HTML.
Un conjunto de layouts ejemplo podría ser el siguiente:
default.html
Una página por defecto. Podría tener este contenido:
-
CABECERA HTML: incluye los estilos CSS (que se van a generar a partir de archivossass) y el favicon (el ícono de la página en las pestañas, historial y marcadores). -
CABECERA_PÁGINA: incluye el título del proyecto en un<h1>(título principal) y su descripción en un<h2>(título secundario). -
CONTENIDO: simplemente muestra el contenido del post o la página -
PIE DE PÁGINA: se pueden agregar datos de contacto, de copyright, etc.
Van a ver que hay código entre llaves, es código dinámico que lee propiedades seteadas en la configuración o en el Front Matter del post o página que se está creando.
home.html
La página principal:
PORTADA: lugar para poner una imagen de portadaPOSTS: muestra los títulos y las descripciones de los postsPAGINADO: muestra los controles de paginados
Notar el Front matter que está entre dos juegos de tres guiones (---). layout toma el layout correspondiente e inserta la página en la etiqueta content del layout.
post.html
POST: muestra el post con su autor, fecha y contenidoCOMENTARIO FINAL: un lugar para escribir que se repite en todos los posts.
Estilos
Los estilos están definidos en archivos .scss en el directorio _sass.
La configuración completa está en el nuevo post Estilos en Sass para Jekyll
No voy a entrar mucho en sass ni css, pero básicamente los primeros se convierten en los segundos.
Posts
En el directorio _posts se escriben los posts en formato Markdown. La guía de Markdown también queda para otro día.
Con el Front Matter se definen los metadatos del post:
---
layout: post
title: "<Título artículo>"
date: 2022-04-02 20:00:00 -0300
categories: categoria1, categoria2
author: Nombre Apellido
permalink: 2022-04-02-Titulo-articulo
excerpt: "Este es el resumen que se va a ver en la página principal"
---
Acá escribo mi artículo en `Markdown`.
Recursos
En el directorio _assets se pueden guardar los recursos que queremos subir, como las imágenes. Para eso podemos hacer un directorio images y adentro subcarpetas por artículo, por ejemplo.
Conviene enlazar las imágenes directamente desde la url de subida, por ejemplo:
Borradores
Todo lo que esté dentro del directorio docs y empiece con un guion bajo (_) se ignora. Entonces podemos tener un directorio de borradores, por ejemplo _drafts, en la que tengamos los borradores de los artículos que estamos escribiendo o aunque sea los nombres de los que pensamos escribir.
Probando la configuración
Una vez que tenemos los layouts y los estilos ya podemos crear la página principal: index.html (tiene que ser html para que la paginación funcione). Puede ser tan simple como:
---
title: "Página principal"
layout: home
---
En este caso solo toma el layout home y le pone de título “Página principal”.
Probando local
Vamos a la consola y hacemos que jekyll levante nuestro sitio:
$ bundle exec jekyll s --port <puerto> --host 0.0.0.0
Los argumentos --port y --host son opcionales. El primero setea el puerto donde se sirve el contenido (default: 4000). El segundo permite acceder el sitio desde otras computadoras de la red.
Probando en el servidor
Vamos a la consola y agregamos todos los cambios:
git add .
Creamos un commit con los cambios y un mensaje:
git commit -m "configuración inicial"
Y subimos la rama gh-pages a nuestro repo
git push --set-upstream origin gh-pages
Si hicimos todo bien, en https://mi-usuario.github.io/mi-repo deberíamos tener la página principal del blog.
Para terminar la configuración hay que ir a Settings debajo del nombre del repositorio a la derecha:
Dentro de los menúes de Settings, hay que ir a Pages:
En la parte que dice Source, elegir el directorio docs de la rama gh-pages.
Ahora podemos ir a la dirección que aparece en la parte superior de la misma página de Pages:
Se debería ver así:
Podemos ver que la imagen está rota, porque no tenemos ninguna portada, y el link Acerca de no lleva a ningún lado.
Agregando una página estática
Para crear una página podemos crearla dentro de docs, puede ser en Markdown o en HTML.
En este caso vamos a escribir el Acerca de en Markdown (about.md):
---
layout: page
title: Acerca de
---
Este es un blog de prueba para mostrar cómo
se hace un blog en [Jekyll](https://jekyllrb.com/).
Guardamos el archivo y lo agregamos:
git add .
Creamos el commit:
git commit -m about.md
Subimos los cambios:
git push
En la pestaña Actions se puede ver el estado del despliegue:
Podemos ver el despliegue actual en amarillo:
Y cuando se pone en verde, hacemos click en el link Acerca de de la página principal:
Para corregir la imagen solo hay que crear un archivo portada.png en el directorio docs. Si se quiere usar otro formato, también hay que cambiar el layout home.html.
Otra vez git add ., git commit -m portada, git push, esperamos a que el trabajo se ponga en verde. El resultado:
Agregando un post
Ahora sí, vamos a agregar un post. Los posts van en el directorio _posts y el formato del nombre lleva la fecha: es AAAAMMDD-titulo-post.md.
Por ejemplo, creemos el post 2022-04-08-Mi-primer-post.md:
---
layout: post
title: "Mi primer post"
date: 2022-04-08 22:55:00 -0300
categories: meta
author: Jose Arcidiacono (@mokocchi)
permalink: 2022-04-08-Mi-primer-post
---
Este es mi primer entrada de blog.
Voy a decir algunas cosas **importantes**.
## Lista
- Una cosa
- Otra cosa
La cabecera del archivo tiene los metadatos, y el contenido se escribe en Markdown. Esta vez usamos el layout post. El post no va a aparecer hasta el momento indicado por Date, que resulta útil para prgramar posts. El permalink, como su nombre lo indica, no debería cambiar una vez que está publicado el artículo. El campo excerpt (no está en este post) permite personalizar el resumen que se va a mostrar en la página principal.
add, commit, push…
Primero vamos a la página principal.
Aparece el título del post con un extracto. Hacemos click y se muestra el post completo:
¡Y ya está!
Ya tenemos la página principal, una página estática y un post.
Por comentarios o sugerencias mi correo está al final de la página. También pueden levantar un issue en el repo de GitHub del sitio.