En el primer artículo de esta serie, estudiamos los fundamentos de Jekyll y creamos un primer sitio estático sencillo. En esta entrega aprenderemos a compilar el sitio estático en nuestra propia máquina para probarlo en local antes de subirlo a Github. También veremos cómo componer publicaciones y ver los resultados.
Compilación local
Jekyll es un programa escrito en Ruby, y por tanto es necesario instalar el intérprete de este lenguaje para usarlo en nuestro ordenador. Los pasos a seguir variarán según el sistema operativo que usemos: en Windows conviene usar RubyInstaller, en macOS podemos usar brew o alguna de las herramientas RVM y rbenv, y en distribuciones de Linux el intérprete suele estar disponible en todos los repositorios de paquetes.
Una vez instalado, abrimos la terminal correspondiente y ejecutamos ruby --version para comprobar que se ha instalado correctamente.
Los programas y librerías de Ruby suelen publicarse en un repositorio denominado Rubygems al que tendremos acceso mediante el comando gem. Para instalar Jekyll, ejecutaremos:
gem install github-pages
si pretendemos publicar nuestro sitio en GitHub
Si no quisiésemos publicar en Github podemos instalar tan solo el repositorio de Jekyll:
gem install jekyll
Otra forma de realizar esta instalación sería especificar las dependencias en un archivo Gemfile que puede que venga incluido en el tema que hayamos usado. Para esto, basta con ejecutar los siguientes comandos:
gem install bundler
bundle install
Cuando Jekyll y sus dependencias estén instalados, podemos compilar y servir localmente nuestro sitio utilizando la opción serve:
jekyll serve
o bien si utilizamos la Gemfile:
bundle exec jekyll serve
Jekyll debería compilar en pocos segundos el sitio web y servirlo en localhost:4000, a donde podremos acceder desde nuestro navegador favorito.
Mientras Jekyll siga ejecutándose, además, recompilará el sitio cada vez que añadamos o modifiquemos archivos. Para detener el servidor basta con pulsar <kbd>Ctrl</kbd>+<kbd>C</kbd>.
Es importante comprobar cuál es la dirección raíz de nuestro sitio web. Si el parámetro baseurl del archivo _config.yml tiene un valor distinto de la cadena vacía, entonces el sitio se publicará en esa URL. Por ejemplo, si tenemos la línea baseurl: "/blog" deberemos acceder a localhost:4000/blog.
Datos iniciales
Al componer cualquier página en Jekyll, es necesario proporcionar una serie de datos en formato YAML para que el compilador los procese. Se suele denominar a esta sección de metadatos front matter.
Generalmente se indica, como mínimo, la plantilla de distribución de contenidos (layout) que debe seguir la página, y el título. La plantilla hace referencia al archivo del mismo nombre (y extensión .html o .md) que encontrarás en el directorio _layouts del tema de Jekyll que hayas elegido. Tras esta sección de datos, delimitada con exactamente tres guiones ---, se incluiría el contenido de la página.
La front matter puede contener tantas asignaciones como queramos, y estas estarán disponibles en el contenido en la variable page (aprenderemos más sobre variables y cómo usarlas en la siguiente parte). Algunos parámetros útiles son published, que indica si un post debe estar visible o no; category, que especifica una categoría, y tags, que puede listar las etiquetas asociadas a un post.
Por ejemplo, este sería el contenido de una página .md que crearíamos para que lo procese Jekyll:
---
layout: post
title: Título de la publicación
author: David Charte
category: programación
tags:
- jekyll
- ruby
---
¡El contenido de esta publicación es un borrador!
Los archivos que no contengan front matter se copiarán tal cual en el sitio web compilado sin ser procesados por Jekyll, lo cual es útil para archivos auxiliares como hojas de estilos y código JavaScript.
En ocasiones habrá archivos que queremos que Jekyll procese pero que no son páginas propiamente, como hojas de estilos SCSS (Sass) o guiones CoffeeScript que queremos que se compilen a CSS y JS, respectivamente al mismo tiempo que se compila el sitio web. En este caso es necesario proporcionar una sección de datos vacía. Por ejemplo, para un archivo SCSS:
---
---
body { background: white; }
// Estilos SCSS
Composición de publicaciones con Kramdown
Jekyll incorpora soporte para composición en Markdown además de HTML. Todos los archivos (plantillas, publicaciones y páginas) que utilicen las extensiones .md y .markdown serán procesados por el conversor Kramdown para generar código HTML. Kramdown es una extensión del lenguaje de marcado Markdown que añade bastante funcionalidad útil. Puedes consultar los detalles de sintaxis, a continuación te muestro lo más relevante en un ejemplo:
# Tablas
| Columna primera | Columna segunda |
|:----------------|----------------:|
| Datos alineados | Datos alineados |
| a la izquierda | a la derecha |
# Código con resaltado
~~~javascript
var theAnswer = 42;
~~~
# Matemáticas con MathJax
Podemos escribir en $$\LaTeX$$ fórmulas y ecuaciones:
$$ e^{i\tau} - 1 = 0 $$
# Notas y abreviaturas
Para referencias y notas a pie de página, es útil esta sintaxis[^kramdown]. En
HTML, una abreviatura se denota con la marca `<abbr>`.
[^kramdown]: <https://kramdown.gettalong.org/syntax.html>.
*[HTML]: Hyper Text Markup Language
Algunas observaciones sobre esta funcionalidad:
Ahora es tu turno, crea una nueva publicación en el archivo _posts/YYYY-MM-DD-titulo-post.md, por ejemplo 2019-01-21-Mi-Primer-Post.md, y comienza a escribir enél usando Markdown. No te olvides de incluir el front-matter tal y como hemos visto. Cuando termines, compila el sitio si no lo has hecho aún y comprueba el resultado.
Paginación
Cuando hayamos acumulado varios posts, lo habitual será mostrar en la página principal los más recientes y tener páginas siguientes con los anteriores. Jekyll permite esta funcionalidad con el plugin paginador.
En algunos temas vendrá ya incluido. Si no es así tendremos que requerirlo desde la configuración para poder usarlo. Para ello añadiremos la siguiente línea al Gemfile y reinstalaremos dependencias ejecutando bundle (alternativamente, ejecutaremos gem install jekyll-paginate):
gem 'jekyll-paginate'
Asimismo, añadiremos el plugin a la lista de plugins en _config.yml:
plugins:
- jekyll-paginate
# número de posts por página
paginate: 5
Ahora, cuando Jekyll compile nuestro sitio proporcionará una variable site.paginator de donde podremos extraer cada página de posts. Las páginas se basarán en el archivo index.html de la raíz del sitio. Para aprovecharlo, usamos un código como el siguiente en dicho archivo:
{% for post in paginator.posts %}
<div class="post">
<h1>{{ post.title }}</h1>
{{ post.content }}
</div>
{% endfor %}
<nav class="pagination">
{% if paginator.previous_page %}
<a href="{{ paginator.previous_page_path }}">Más nuevo</a>
{% endif %}
{% if paginator.next_page %}
<a href="{{ paginator.next_page_path }}">Más antiguo</a>
{% endif %}
</nav>
El resultado debería ser una lista de posts truncada en el número que hayamos especificado en la configuración y un enlace a los posts anteriores.
En el próximo artículo de esta serie entraremos de lleno en el código de plantillas que procesa Jekyll, denominado Liquid Markup, y otros aspectos que nos ayudarán a personalizar nuestra web. Hasta entonces, espero que te hayas familiarizado con la estructura de directorios que usa Jekyll y hayas aprendido a añadir posts a tu nuevo sitio estático.
Crea tu propia página o blog gratis con Jekyll y Github - Serie completa:
Fecha de publicación: