Fork me on GitHub
(Descarga la versión en )

Jekyll

Jekyll

Jekyll es un tipo de CMS especial. Pertenece a la categoría de Headless CMS también llamados Static Site Generator.

En este tipo de CMS no necesitamos un lenguaje de programación en la parte del servidor, porque todo el contenido es estático. Ahora bien, si el contenido es estático, ¿dónde está la ventaja?

Pues la ventaja viene porque estos CMS generan contenido estático a partir de ficheros fuente, sin necesidad de tener ni tan siquiera una base de datos.

Este contenido estático, pero generado dinámicamente, es el que compone nuestra aplicación.

Cuáles son las ventajas

  • Menos complejos
  • Mayor velocidad
  • Mayor seguridad
  • Mayor escalabilidad
  • Control de versiones

Top ten

Más información acerca de Headless CMS

Para nuestra página personal de GitHub vamos a usar Jekyll, pues es mantenido por el propio GitHub y es soportado nativamente.

Instalación

Jekyll está basado en Ruby, por lo que el primer paso es instalar Ruby

1

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

Después hay que configurar nuestras variables de entorno para no tener que usar sudo al instalar gemas (las gemas son como los paquetes de composer de PHP o npm de node.js)

1
2
3
4

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 instalar, Jekyll

1

gem install jekyll bundler

Más información en:

https://jekyllrb.com/docs/installation/ubuntu/

Primera aplicación

Primero vamos a clonar nuestro repositorio personal de GitHub en un directorio local.

1
2
3

mkdir tu-usuario.github.io.git 
cd tu-usuario.github.io.git 
git clone https://github.com/tu-usuario/tu-usuario.github.io.git .

Y creamos nuestra primera página:

1
2
3
4
5
6
7
8
9
10

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Home</title>
  </head>
  <body>
    <h1>Hello World!</h1>
  </body>
</html>

Build

Jekyll es un generador de sitios estáticos, por lo que necesitamos que Jekyll construya el sitio antes de poder verlo. Hay dos comandos que puedes ejecutar en la raíz de tu sitio para construirlo:

  • jekyll build: crea el sitio y genera un sitio estático en un directorio llamado _site.
  • jekyll serve --livereload: hace lo mismo, excepto que se reconstruye cada vez que se realiza un cambio y ejecuta un servidor web local en http://localhost:4000.

Estructura Directorios Jekyll

Parece que no hace mucho, ya que sólo ha copiado los archivos al directorio _site, pero ya veremos que puede hacer muchas más cosas.

Hello World Jekyll

Como queremos actualizar nuestra página personal, vamos a hacerlo directamente con git. En el caso de subir la web a GitHub, hemos de ignorar el directorio _site, mediante .gitignore ya que es el propio GitHub quien generará automáticamente nuestra web.

Y desplegamos nuestra primera versión haciendo un push.

1
2
3
4

git add .gitignore
git add index.html
git commit -m "jekyll"
git push

Github Web Pages

Y ahora visitamos https://victorponz.github.io/

victorponz.github.io

GitHub se ha encargado de todo y ha generado la página personal.

Liquid

Liquid es donde Jekyll comienza a ponerse más interesante. Liquid es un lenguaje de plantillas que tiene tres partes principales: objetos, etiquetas y filtros.

En esta página tenéis información de cómo usar Liquid en Jekyll.

Ahora cambia index.html

1
2
3
4
5
6
7
8
9
10
11
12
13

---
---
<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Home</title>
  </head>
  <body>
    <h1>{{ "Hello World!" | downcase }}</h1>
  </body>
</html>

Liquid

Hemos usado el primer objeto, la parte que va entre `` de Liquid y el primer filtro: downcase

Front Matter

Front Matter es un fragmento de YAML que se encuentra entre dos líneas de tres puntos en la parte superior de un archivo. Front Matter se utiliza para establecer variables para la página, por ejemplo:

1
2
3

---
my_number: 5
---

Estas variables son accesibles en Liquid mediante la variable page

Por ejemplo, para imprimir esta variable en una plantilla:

1

{{ page.my_number }}

Vamos a usar una variable titleen nuestro Front matter

1
2
3
4
5
6
7
8
9
10
11
12
13

---
title: Home
---
<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    <h1>{{ "Hello World!" | downcase }}</h1>
  </body>
</html>

De momento, tampoco ha cambiado nada. Luego le daremos más funcionalidad.

Layouts

Si queremos hacer una nueva página, por ejemplo about.html podríamos copiar index.html y modificarlo.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

---
title: About
---
<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    <h1>About page</h1>
    <p>This page tells you a little bit about me.</p>
  </body>
</html>

Pero claro, ¿dónde está la ventaja de usar Jekyll si todo lo hacemos de esta forma?

La respuesta está en los Layouts.

Primero, creamos un directorio llamado _layouts y creamos un nuevo archivo llamado default.html con el siguiente código:

1
2
3
4
5
6
7
8
9
10

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

Es parecido al código a anterior, pero no tiene Front matter y el contenido de la página está reemplazado con la variable Liquid content

Para que index.html use este layout, reemplaza todo el contenido por

1
2
3
4
5

---
layout: default
title: Home
---
<h1>{{ "Hello World!" | downcase }}</h1>

Y reemplaza el código de about.html:

1
2
3
4
5
6

---
layout: default
title: About
---
<h1>About page</h1>
<p>This page tells you a little bit about me.</p>

Includes

Ahora tenemos dos páginas pero no hay forma de navegar entre ellas.

Para ello usamos el tag include y colocamos el código en un archivo dentro del directorio _includes

Creamos nuestro primer include en _includes/navigation.html

1
2
3
4

<nav>
  <a href="/">Home</a>
  <a href="/about.html">About</a>
</nav>

Y ahora lo usamos en default.html

1
2
3
4
5
6
7
8
9
10
11

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    {% include navigation.html %}
    {{ content }}
  </body>
</html>

navigation

Resaltar la página actual

Usamos una de las variables que proporciona Jekyll automáticamente: page.url

1
2
3
4
5
6
7
8

<nav>
  <a href="/" {% if page.url == "/" %}style="color: red;"{% endif %}>
    Home
  </a>
  <a href="/about.html" {% if page.url == "/about.html" %}style="color: red;"{% endif %}>
    About
  </a>
</nav>

Todavía hay mucha repetición aquí si desea agregar un nuevo elemento a la navegación o cambiar el color de resaltado. En el siguiente paso abordaremos esto.

Data Files

Jekyll admite la carga de datos desde archivos YAML, JSON y CSV ubicados en un directorio _data. Los archivos de datos son una excelente manera de separar el contenido del código fuente para hacer que el sitio sea más fácil de mantener.

En este paso, almacenaremos el contenido de la navegación en un archivo de datos y luego iteraremos sobre él en el include de navegación.

YAML es el formato que más común en el ecosistema de Ruby. Lo usaremos para almacenar una serie de elementos de navegación, cada uno con un nombre y un enlace.

Crea un archivo de datos para la navegación en _data/navigation.yml con lo siguiente:

1
2
3
4

- name: Home
  link: /
- name: About
  link: /about.html

Jekyll pone este archivo de datos a tu disposición en la variable site.data.navigation. En lugar de mostrar cada enlace en _includes/navigation.html, ahora podemos iterar sobre el archivo de datos:

1
2
3
4
5
6
7

<nav>
  {% for item in site.data.navigation %}
    <a href="{{ item.link }}" {% if page.url == item.link %}style="color: red;"{% endif %}>
      {{ item.name }}
    </a>
  {% endfor %}
</nav>

Si ahora añadimos una nueva entrada en navigation.yml, automáticamente creará el nuevo enlace:

1
2
3
4
5
6

- name: Home
  link: /
- name: About
  link: /about.html
- name: Nueva
  link: /nueva.html

Menú con YAML

Assets

El uso de CSS, JS, imágenes y otros recursos es sencillo con Jekyll. Colócalos en la carpeta de tu sitio y se copiarán al sitio creado.

Los sitios de Jekyll a menudo usan esta estructura para mantener los activos organizados

1
2
3
4
5
6

.
├── assets
|   ├── css
|   ├── images
|   └── js
...

SASS

Los estilos en línea utilizados en _includes/navigation.html no son las mejores prácticas, vamos a diseñar la página actual con una clase css.

1
2
3
4
5

<nav>
  {% for item in site.data.navigation %}
    <a href="{{ item.link }}" {% if page.url == item.link %}class="current"{% endif %}>{{ item.name }}</a>
  {% endfor %}
</nav>

Puedes usar un archivo CSS estándar para el estilo, vamos a ir un paso más allá usando Sass. Sass es una fantástica extensión de CSS incluida directamente en Jekyll.

Primero crea un archivo Sass en /assets/css/styles.scss con el siguiente contenido:

1
2
3

---
---
@import "main";

El front matter vacío en la parte superior le dice a Jekyll que necesita procesar el archivo.

@import "main" le dice a Sass que busque un archivo llamado main.scss en el directorio sass (_sass/ por defecto).

Así que creamos el archivo _sass/main.scss con el siguiente contenido:

1
2
3

.current {
    color: green;
}

Deberemos hacer referencia a la hoja de estilo en el diseño.

Abre _layouts/default.html y agrega la hoja de estilo al <head>:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
    <link rel="stylesheet" href="/assets/css/styles.css">
  </head>
  <body>
    {% include navigation.html %}
    {{ content }}
  </body>
</html>

scss

Blogging

Quizás te preguntes cómo puedes tenes un blog sin una base de datos. En el verdadero estilo Jekyll, los blogs solo funcionan con archivos de texto.

Posts

Las publicaciones de blog se almacenan en una carpeta llamada _posts. El nombre de archivo de las publicaciones tiene un formato especial: la fecha de publicación (yyyy-mm-dd), luego un título, seguido de una extensión.

Crea tu primera publicación en _posts/2019-01-17-primera-entrada.md con el siguiente contenido:

1
2
3
4
5
6

---
layout: post
author: victor
---
# Esta es mi primera entrada de blog
Está en formato markdown, por lo se puede usar cualquier editor de markdown como typora o instalar una extensión para Visual Studio Code.

http://jmcglone.com/guides/github-pages/

https://help.github.com/articles/adding-a-jekyll-theme-to-your-github-pages-site-with-the-jekyll-theme-chooser/

Layout

El layout post no existe, así que vamos a crearlo con el siguiente contenido:

1
2
3
4
5
6
7

---
layout: default
---
<h1>{{ page.title }}</h1>
<p>{{ page.date | date_to_string }} - {{ page.author }}</p>

{{ content }}

Este es un ejemplo de herencia de diseño. El layout post genera el título, la fecha, el autor y el cuerpo del contenido, que está incluido en el diseño predeterminado (hereda de default)

También aplica el filtro date_to_string, que da formato a una fecha en un forma más agradable.

Listas de Posts

Actualmente no hay manera de navegar a la publicación del blog. Normalmente, un blog tiene una página que enumera todas las publicaciones, hagámoslo a continuación.

Jekyll pone las publicaciones disponibles en la variable site.posts.

Crea blog.html en tu raíz (/blog.html) con el siguiente contenido:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

---
layout: default	
title: Blog
---
<h1>Latest Posts</h1>

<ul>
  {% for post in site.posts %}
    <li>
      <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
      <p>{{ post.excerpt }}</p>
    </li>
  {% endfor %}
</ul>

Hay algunas cosas a tener en cuenta con este código:

  • Jekyll establece automáticamente post.url en la ruta de salida de la publicación.
  • post.title se extrae del nombre de archivo de la publicación y se puede anular configurando el título en el front matter.
  • post.excerpt es el primer párrafo de contenido por defecto

También necesitamos una forma de navegar a esta página a través de la navegación principal. Abre _data/navigation.yml y agrega una entrada para la página del blog:

1
2
3
4
5
6

- name: Home
  link: /
- name: About
  link: /about.html
- name: Blog
  link: /blog.html

Y este es el resultado:

Lista de blogs

Entrada de blog

Más posts

Crear una nueva entrada es tan sencillo como crear otro archivo en _posts

Por ejemplo, _posts/2020-11-11-headless-cms.md

1
2
3
4
5
6
7
8
9
10
11

---
layout: post
author: victor
title: ¿Qué es un Headless CMS?
excerpt: En esta entrada se explica qué es un Headless CMS
---
# Headless CMS
A headless content management system, or headless CMS, is a back-end only content management system (CMS) built from the ground up as a content repository that makes content accessible via a RESTful API for display on any device.

The term “headless” comes from the concept of chopping the “head” (the front end, i.e. the website) off the “body” (the back end, i.e. the content repository).

Nueva entrada

Otra entrada

Actualizar nuestro repo en GitHub Pages

Ya sólo nos queda subir los cambios a GitHub y ya tenemos nuestra página personal.

Repositorio actualizado

Una vez subimos los archivos, GitHub tiene que construir el sitio mediante Jekyll. Así que a veces no es automático.

Para ver el estado de vuestro sitio, id a Settings

GitHub Pages Settings

En este caso dice:

1

Your GitHub Pages site is currently being built from the master branch

A veces tarda bastante en actualizar, pero está en ello!

Acualizado

Uso de GitHub Pages sin Jekyll

No es necesario realizar nuestro sitio con Jekyll. Lo podemos realizar con cualquier Headless CMS e incluso hacerlo a la antigua usanza.

Otra opción posible es hacerlo con Jekyll pero que nuestro repositorio apunte al directorio _site en vez de a raíz. De esta forma al hacer un git push no nos hemos de esperar a que GitHub procese nuestro sitio.

Por ejemplo, supongamos que hemos hecho ya un commit de _site al repositorio:

Tree clean

Ahora modificamos _layouts/post.hml:

1
2
3
4
5
6

---
layout: default
---
<h1>Víctor Ponz</h1>
<h1>{{ page.title }}</h1>
<p>{{ page.date | date_to_string }} - {{ page.author }}</p>

Y ahora el estado del repositorio es:

Modificado

Por lo que ya podría subir nuestros cambios a GitHub Pages

Ejemplos

En la siguiente dirección encontraréis más ejemplos de páginas personales.

https://github.com/topics/personal-website

Blog prediseñado para impacientes

Podemos crear un blog ya prediseñado haciendo uso de los siguientes comandos:

  1. Creamos el blog con el nombre myblog

    1

    jekyll new myblog

  2. Cambiamos al directorio ./myblog

    1

    cd myblog

  3. Creamos el sitio y los publicamos en el servidor

    1

    bundle exec jekyll serve

  4. Navegamos a 127.0.0.1:4000

Blog prediseñado

Disqus

Vamos a integrar Disqus en nuestra página personal.

Disqus is a networked community platform used by hundreds of thousands of sites all over the web. With Disqus, your website gains a feature-rich comment system complete with social network integration, advanced administration and moderation options, and other extensive community functions. Most importantly, by utilizing Disqus, you are instantly plugging into our web-wide community network, connecting millions of global users to your small blog or large media hub.

Disqus works on just about any type of website or blog and can be installed either with a drop-in code snippet or by using one of the plugins available on our Install page. You can also customize and tweak Disqus for your website with extensive APIs and JavaScript hooks. Check out the Quick Start Guide or visit our homepage for more information and a demo of Disqus.

El primer paso es registrarse en Disqus.

Una vez os habéis registrado, seleccionad I Want to install Disqus on my site

Disqus

Y completad el formulario con la url de vuestra página personal de GitHub

New Site

Seleccionad la opción Free!!

Free Plan

Finalmente, elegid Jekyll

Jekyll CMS

Ahora lo único que hay que hacer es modificar post.html, añadiendo el código que provee Disqus

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<hr>
<div id="disqus_thread"></div>
<script>
var disqus_config = function () {
    this.page.url = 'https://username.github.io//tema1/git/2020/11/03/jekyll.html';  // Replace PAGE_URL with your page's canonical URL variable
};
(function() { // DON'T EDIT BELOW THIS LINE
var d = document, s = d.createElement('script');
s.src = 'https://https-username-github-io.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>

Reemplazando usernamepor tu página personal de GitHub y con el código la url que te ha generado Disqus

Aquí os dejo el enlace para instalarlo en Jekyll, por si tenéis algún problema.

Y este es el resultado:

Disqus

Tarea - Página con Jekyll

Crea tu página personal con jekyll

Ten en cuenta que todas las prácticas de este módulo las crearás en tu página personal de GitHub