jekyll-readme-index: utiliza el README.md de tu repo como home de tu blog

Este plugin te permite utilizar la información que muestres en el fichero README.md del repo como página de inicio de tu blog.

Fecha: 29 Jul 2023 - Autor: Antonio

Post en Categoría: Blogging

Etiquetas: / how-to / jekyll-plugins /

Citando textualmente la documentación del plugin jekyll-readme-index:

A Jekyll plugin to render a project’s README as the site’s index.

Es decir, un plugin para renderizar el fichero README.md del repositorio de GitHub donde albergamos nuestra web como el index o el home de la misma.

Digamos que tienes un repositorio de GitHub con un fichero README.md que te gustaría utilizar como página principal de una web alojada en GitHub Pages. Podrías renombrar el fichero como index.md, pero entondes dejaría de ser renderizado en GitHub.com. Podrías añadir un front matter de YAML con el valor permalink: / en el README, pero ¿Porqué forzar a un humano a hacer aquello que Jekyll puede automatizar?

Si tienes un fichero README, y tu web no tendría una mejor página principal, este plugin indica a Jekyll la manera de utilizar el README.md como index del sitio web. Nada más, nade menos

1. Instalación y configuración

  1. Añade lo siguiente a al fichero Gemfile de tu proyecto Jekyll.
# file: "Gemfile"
gem "jekyll-readme-index"
  1. Añade lo siguiente en el fichero _config.yml
# file: "_config.yaml"
plugins:
  - jekyll-readme-index
  1. Por último, para que los cambios tengan validez en nuestro entorno local deberemos ejecutar el comando: bundle

Existen configuraciones adicionales que se especifican en la documentación oficial del plugin, en nuestro caso no aplican.

2. Confección del fichero README.md

Realmente el fichero README.md del repositorio donde estoy alojando la web no decía mucho. Unos pocos encabezados y algún link hacia el propio blog.

Unos días antes estuve configurando el README.md de mi perfil de GitHub, y la verdad quedé bastante contento con el resultado. Lo que hice fue seguir esta guía y adaptarla a mi gusto.

Por lo tanto ya tenía la mitad del trabajo hecho. Para el README.md del proyecto del blog. Cogí el de mi perfil de GitHub y lo simplifiqué un poco más además de traducirlo al castellano. Puedes ver el contenido del fichero a continuación.

Detalle del código utilizado en el fichero README.md

Aquí puedes ver el código markdown y html que han sido utilizados en el fichero README.md

3. Recursos

Documentación oficial del plugin: jekyll-readme-index.

Guía completa para hacer un README.md molón en tu perfil de GitHub.

Artículos relacionados

Posts

Pages