Páginas de contenido

El contenido es la parte más importante de un sitio web. En Jekyll, se distingue principalmente entre archivos estáticos, de páginas y de artículos.

Al finalizar, sabrá:

Qué es un archivo de contenido.
Qué diferencia hay entre un archivo transformable y uno estático.
Qué es una página de contenido.
Qué es el encabezamiento (front matter) de un archivo de contenido.
Cómo definir propiedades personalizadas en un encabezamiento.
Qué son los archivos de diseño (layout files).
Cómo agrupar contenido mediante colecciones.
Cómo indicar la página que debe devolver GitHub Pages cuando el usuario indique una ruta inexistente.

Introducción

El contenido de un sitio web (website content) es la colección de recursos que proporciona y pueden consultar los usuarios. Recordemos que un generador de sitios webs estáticas (static site generator) no es más que una aplicación que transforma un directorio en un sitio web de contenido estático. Esto es lo que es Jekyll, ni más ni menos, un programa que transforma un directorio en un determinado sitio web estático para que pueda ser servido por cualquier servicio o servidor web como, por ejemplo, GitHub Pages, Apache o Nginx.

Atendiendo a si los archivos de contenido deben ser transformados en HTML o deben ser copiados tal cual, se distingue entre archivos transformables y estáticos. Un archivo transformable (renderizable file) es aquel que debe procesar de alguna manera el generador para obtener su equivalente en HTML. En nuestro caso, puede ser un archivo Markdown o bien un HTML, en ambos casos, con contenido dinámico indicado mediante expresiones o etiquetas Liquid. Mientras que un archivo estático (static file) es aquel que no será procesado y se copiará tal cual al resultado final como, por ejemplo, una imagen , un PDF o cualquier otro tipo de archivo que no deseamos sea procesado internamente por el generador, en nuestro caso, Jekyll.

En Jekyll, los archivos transformables se clasifican en páginas y artículos. En esta lección, vamos a presentar las páginas, dejando los artículos para una posterior.

Páginas de contenido

Una página (page) es un archivo o recurso de contenido que puede estar escrito en Markdown o HTML. Estos archivos son archivos transformable y, por lo tanto, se consideran plantillas con elementos Liquid en su interior que personalizan su contenido final en tiempo de generación. Es importante que tenga claro que cuando Jekyll está generando el sitio web final y se encuentra con un archivo Markdown, acabará generando un archivo HTML. Para facilitar la agrupación de las páginas por cualquier tipo de criterio, podemos organizarlas en carpetas (folders), cada una de las cuales se representa mediante un directorio.

Las páginas, a diferencia de otros archivos, se pueden ubicar en cualquier directorio.

Encabezamiento de la página

Tanto las páginas como los artículos, pueden tener lo que se conoce formalmente como un encabezamiento (front matter) que contiene los metadatos de la página en forma de propiedades cuyo formato es nombre: valor. Se ubica al comienzo del archivo y se delimita por tres guiones (---), tal y como muestra el siguiente ejemplo:

---
title: Título de la página si se desea personalizar
layout: archivo de diseño a utilizar
permalink: /ruta/donde/publicar/la/página
---

Los encabezamientos indicados explícitamente son lo que utiliza Jekyll para determinar si está ante un archivo estático o uno transformable. Si dispone de él, es un archivo transformable y debe procesarlo como tal; en otro caso, es estático y debe copiarlo tal cual a la salida.

Entre las propiedades del encabezamiento de las páginas, encontramos:

Propiedad	Tipo de datos	Descripción
*title*	Texto	Título de la página, debe ser descriptivo de su contenido.
*layout*	Texto	Archivo de diseño a utilizar como, por ejemplo, *base, page* o *post*.
*permalink*	Texto	Ruta de la página dentro del sitio web.
*description*	Texto	Breve descripción de la página, añadido como metadato HTML.
*slug*	Texto	Parte final de la ruta que identifica la página.
*render_with_liquid*	Booleano	Si Jekyll debe usar Liquid en esta página. Su valor predeterminado es *true; indique false* si no desea que lo use. Disponible desde la versión 4.0.

Recuerde que el encabezamiento debe aparecer al comienzo de la página y puede hacerlo tanto en archivos Markdown como HTML. Más adelante hablaremos de los archivos de diseño (layouts), archivos que definen el diseño con el que se publicará la página. Atendiendo al tema que utilicemos en el sitio, se definirán unos u otros. Incluso nuestro sitio puede añadir los suyos propios.

Un enlace permanente (permalink) es la ruta bajo la cual Jekyll publicará la página de contenido. Se indica mediante la propiedad permalink del encabezamiento de la página.

Si decide indexar su sitio web en algún buscador como, por ejemplo, Google, es recomendable que recuerde lo siguiente:

Se recomienda que el título de la página y del sitio contengan entre 20 y 70 caracteres, incluidos los espacios en blanco. Para su mejor indexación, no olvide que aparezcan las palabras claves.
Las descripciones deberían estar entre 70 y 150 caracteres y contener las palabras claves. Estas descripciones aparecen en los resultados de búsqueda, de ahí que se recomiende su definición para cada página y sitio web.
Las rutas de las páginas deben ser descriptivas del contenido que representan.

Puede utilizar WooRank, https://www.woorank.com, para obtener un informe con sugerencias para un mejor posicionamiento de su sitio. No tiene más que indicar el URL de su sitio web y dejar que lo analice para obtener un pequeño informe gratuito que le mostrará algunas recomendaciones que le pueden ayudar.

Archivos de diseño en Jekyll

Un archivo de diseño (layout file) es una plantilla que contiene la estética con la que se presentará el contenido de una página o artículo. Dentro de ellas, se utiliza una expresión {{ content }} para indicar dónde irá el contenido de la página o artículo que se está procesando, permitiendo así que las páginas y los artículos tengan una estética similar. Se ubican en la carpeta especial _layouts del directorio del sitio. Cada archivo ahí ubicado se considera un diseño. Cuando deseemos indicar, en una página o artículo, bajo qué diseño deseamos se genere, lo indicaremos mediante la propiedad layout de su encabezamiento (front matter):

---
title: Título de la página
layout: nombre del archivo de diseño a utilizar, sin extensión
---

Contenido de la página, el cual puede contener, recordemos,
elementos y expresiones Liquid.

Recuerde que, en un archivo de diseño, dónde irá el contenido de la página o el artículo bajo procesamiento, se indica mediante una expresión Liquid como la siguiente:

{{ content }}

He aquí un ejemplo ilustrativo de un archivo de diseño:

<!doctype html>
<html lang="es">
  <head>
      <meta character= "utf-8">
      <title>{{ page.title }}</title>
      <link rel="stylesheet" href="/styles/style.css">
  </head>

  <body>
    Aquí contenido de encabezamiento común a todas las páginas
    que utilicen este diseño.

    {{ content }}

    Aquí contenido de pie común a todas las páginas
    que utilicen este diseño.
  </body>
</html>

Los temas, que presentaremos en una lección posterior, vienen con sus propios archivos de diseño. Así, por ejemplo, el tema minima, que viene de fábrica con Jekyll, proporciona los archivos de diseño base, home, page y post. En cambio, el tema Leap day sólo viene con default. Independientemente del número de archivos de diseño que proporcione el tema que estemos usando, podemos definir los nuestros y, además, sobrescribir los proporcionados.

Propiedades personalizadas de los encabezamientos

Recordemos que los encabezamientos (front matters) contienen los metadatos de los archivos de contenido. Atendiendo a si estamos ante una página o un artículo, Jekyll define unas propiedades predefinidas como, por ejemplo, title, layout o permalink.

Además de estas propiedades predefinidas, también podemos declarar propiedades personalizadas (custom properties) para contener cualquier dato extra necesario para nuestros fines. Cualquier propiedad que no sea una predefinida se considerará como personalizada. Puede utilizar este tipo de propiedades, por ejemplo, para añadir metadatos adicionales, los cuales puede utilizar, si lo desea, en el resultado final mediante Liquid.

Estas propiedades se pueden acceder y utilizar en el sitio web mediante expresiones Liquid. Jekyll crea las variables page o post, según el tipo de archivo, para que podamos acceder a las propiedades de su encabezamiento. El acceso es tan sencillo como:

{{ page.propiedad }}
{{ post.propiedad }}

Colecciones

Una colección (collection) representa un grupo de archivos de contenido. Son muy útiles para agrupar contenido relacionado con algún tema o criterio. Un sitio web puede tener tantas colecciones como necesite, incluso no tener ninguna.

Se definen en el archivo de configuración _config.yaml, en la propiedad collections (collections property). Esta propiedad puede ser de tipo lista de textos o bien un objeto.

Cuando se define como una lista de textos, cada uno de sus elementos representa el nombre de la colección, sin proporcionar ningún tipo de metadato sobre la colección. En este caso, es importante que recuerde que las colecciones tendrán su propiedad output a false. Ejemplo:

# ...

collections:
  - nombre
  - nombre
  - ...

En cambio, cuando se define como un objeto o mapa, cada propiedad representa una colección y su valor contiene sus metadatos. Ejemplo:

# ...

collections:
  # colección sponsorship
  sponsorship:
    title: Patrocinio
    output: true
    permalink: /:collection/:path
    order:
      - patrocinio.md
      - roadmap.md
  
  # colección doc
  doc:
    title: Documentación
    output: true
    permalink: /:collection/:path
    order:
      - instalación.md
      - datos.md
      - catálogos.md
      - registros.md
      - extensiones.md
      - disparadores.md
      - ejecución-distribuida.md
      - plugins.md

Directorios de colección

Para cada colección, tenemos que crear un directorio _nombreColección en el directorio del sitio e introducir en él sus archivos de contenido. Así pues, si definimos una colección doc, definiremos el directorio _doc en el directorio del sitio y ubicaremos ahí sus archivos de contenido.

Propiedad output de las colecciones

La propiedad output (output property) es muy importante en una colección. Si su valor es true, Jekyll generará una página para cada uno de sus archivos; en caso contrario, generará una única página para todos ellos. Lo habitual es true.

Propiedad permalink de las colecciones

La propiedad permalink (permalink property) de una colección se puede utilizar para fijar la ruta de sus documentos. Esta propiedad puede contener los siguientes marcadores de posición (placeholders), o sea, elementos nombrados en cuyo lugar se insertará su valor asociado. Disponemos, entre otros, de los siguientes:

Marcador	Descripción
*:collection*	Nombre de la colección.
*:path*	Ruta del archivo relativa al directorio de la colección.
*:name*	Nombre del archivo de contenido sin su extensión.
*:title*	Si el encabezamiento define la propiedad *slug, se utilizará su valor; en otro caso, se usa :name*.

Así, por ejemplo, si tenemos una colección doc y deseamos fijar la ruta de cada una de sus páginas de contenido, podríamos escribir la siguiente propiedad permalink en la colección sin necesidad de indicarla en las páginas:

# ...

collections:
  doc:
    title: Documentación
    output: true
    permalink: /:collection/:path

El slug es la última parte de la ruta del archivo que lo identifica del resto dentro del directorio en el que se encuentra. Es un término muy utilizado en SEO. Se utiliza para posicionar adecuadamente la página en los buscadores. Así, por ejemplo, el slug de esta lección es páginas-de-contenido. Los buscadores para mejorar el posicionamiento recomiendan que sea descriptivo de su contenido.

Propiedad order de las colecciones

Desde la versión 4.0 de Jekyll, se puede utilizar la propiedad order (order property). Si el orden de las páginas de una colección es importante, podemos usarla para indicar exactamente el orden en que deseamos aparezcan. En esta propiedad de tipo lista, cada uno de sus elementos representa un archivo de contenido. Ejemplo:

# ...

collections:
  doc:
    title: Documentación
    output: true
    permalink: /:collection/:path
    order:
      - instalación.md
      - datos.md
      - catálogos.md
      - registros.md
      - extensiones.md
      - disparadores.md
      - ejecución-distribuida.md
      - plugins.md

En el momento de escribir estas líneas, GitHub Pages utiliza la versión 3.9.3 de Jekyll, por lo que tenemos que utilizar una solución alternativa para este caso. Lo más sencillo es añadir una propiedad numérica personalizada order a los encabezamientos de las páginas de la colección y utilizar el filtro sort de Liquid para realizar la ordenación. Ejemplo:

{%- assign coll = site.collections | where: "label", page.collection | first -%}
{%- assign docs = coll.docs | sort: "order" -%}
{%- for doc in docs -%}
  {%- if doc == page -%}
    <span class="page-link">{{ doc.title | escape }}</span>
  {%- else -%}
    <a class ="page-link" href="{{ doc.url | relative_url }}">{{ doc.title | escape }}</a>
  {%- endif -%}
{%- endfor -%}

La versión de Jekyll utilizada por GitHub Pages se puede consultar en https://pages.github.com/versions.

Acceso a las colecciones mediante Liquid

La variable site.collections contiene una lista con las colecciones dadas de alta en el archivo _config. Cada uno de sus elementos es un objeto que contiene los datos de una colección que, a su vez, dispone, entre otras, de las siguientes propiedades:

Propiedad	Tipo de datos	Descripción
*label*	Texto	Nombre de la colección.
*docs*	Array de objetos	Archivos de contenido, generados a partir de plantillas, asociados a la colección.
*files*	Array de objetos	Archivos de contenido estáticos asociados a la colección.

Si necesita acceder a una determinada colección a partir de su nombre, puede utilizar la variable site como sigue:

site._nombreColección

En cambio, si necesita acceder a una colección a partir del valor de alguna de sus propiedades, utilice el filtro where de Liquid, tal y como muestra el siguiente ejemplo:

site.collections | where: "label", page.collection

Recuerde que el filtro where devuelve una lista. No es raro utilizar, a continuación, un filtro first si sólo nos interesa el primer elemento de la lista devuelta.

Los archivos listados en la propiedad docs de las colecciones son aquellos que definen explícitamente un encabezamiento (front matter). Los que no lo declaran, se tratan como archivos estáticos, files.

Cada objeto de un archivo de contenido dispone de las propiedades definidas en su encabezamiento, además de las siguientes propiedades:

Propiedad	Tipo de datos	Descripción
*url*	Texto	Ruta asociada al documento.
*content*	Texto	Contenido del documento sin transformar.
*output*	Texto	Contenido transformado del documento.
*collection*	Texto	Nombre de la colección a la que está asociado el documento.

Valores predeterminados de los archivos de contenido de las colecciones

Es posible asignar valores predeterminados a propiedades, tanto predefinidas como personalizadas, de los encabezamientos de los archivos de contenido asociados a una colección. Por ejemplo, podemos indicar el valor de la propiedad layout en el encabezamiento de cada página o bien a nivel de colección. Así, si decidimos cambiarlo, sólo tendremos que ir a la configuración de la colección.

Aunque podría pensar que estos valores se fijan en la propiedad de la colección, o sea, en la propiedad correspondiente de collections, no es así. Hay que utilizar la propiedad defaults (defaults property), la cual consiste en una lista de elementos donde cada uno de ellos representa un ámbito de aplicación. Realmente, esta propiedad no fija los valores predeterminados de una colección sino de los archivos de contenido de una determinada ruta. Veamos un ejemplo:

collections:
  doc:
    permalink: /:collection/:path
    # ...

  sponsorship:
    permalink: /:collection/:path
    # ...

defaults:
  # colección doc
  - scope:
      path: ""
      type: doc
    values:
      layout: page
  
  # colección sponsorship
  - scope:
      path: ""
      type: sponsorship
    values:
      layout: page

En caso de una colección, el elemento es similar a:

scope:
  path: ""  # siempre la cadena vacía
  type: ruta-de-la-colección  # generalmente, el nombre de la colección
values: # propiedades con sus valores predeterminados
  layout: archivo-de-diseño
  #...

Recuerde que puede fijar el valor predeterminado de cualquier propiedad, tanto predefinida como personalizada. Si el archivo dispone de un encabezamiento y define su propio valor, este sobrescribirá al fijado en defaults. En caso de tratarse de un archivo estático, los valores así indicados serán sus propiedades.

La propiedad type de scope sirve para indicar a qué tipo de contenido se debe aplicar. Si deseamos que se aplique a todas las páginas de contenido, indicaremos pages; en cambio, para los artículos, posts; y si, como en los ejemplos anteriores necesitamos que se aplique a una determinada colección, el identificador de la colección.

Página de error 404 en Jekyll

Los servidores webs responden con un error 404 Not Found cuando un recurso solicitado no existe. Si no indicamos nada especial, GitHub Pages proporcionará una página de error predeterminada. Si lo deseamos o necesitamos, podemos definir una página de error propia en un archivo 404.md o 404.html ubicado en el directorio del sitio. Ejemplo en Markdown:

---
layout: page
permalink: /404.html
---

# 404

*!Página no encontrada!* :(