Crear un índice de libros

Como ya hemos visto, salvo que establezcamos otra cosa, todos nuestros libros son accesibles mediante una URL que es algo así como:

https://usuario.github.io/nombrerepositorio/

Pero nos gustaría crear una página especial que sirva de presentación, con una lista de todos nuestros libros. Será accesible bajo el nombre:

https://usuario.github.io/

Es decir, usamos el mismo nombre de dominio que asignamos a nuestros libros, pero sin especificar el nombre de repositorio. Esto se logra creando un repositorio especial cuyo nombre es usuario.github.io, incluyendo los puntos como parte del nombre y cambiando usuario por nuestro nombre.

Por ejemplo, en el caso de este cuaderno:

• Página de proyecto:

  • URL: https://trezebits.github.io/tutorial_mdBook/
  • Repositorio: https://github.com/trezebits/tutorial_mdBook/

• Página principal, con índice de cuadernos:

  • URL: https://trezebits.github.io/
  • Repositorio: https://github.com/trezebits/trezebits.github.io/

Jeckyll

mdBook es un escelente generador de páginas web, pero no es el único. Si subimos archivos markdown directamente, GitHub hace uso internamente de un conversor llamado Jeckyll, más potente que mdBook, pero también más complejo.

Para un proyecto de página única, sin grandes alardes, vamos a hacer uso de Jeckyll.

Página de índice

El primer paso es crear una carpeta de proyecto en nuestro entorno local, por ejemplo, indice/, como haríamos con cualquier libro. Tratándose de un proyecto tan simple, no vamos a tener subcarpetas.

Seguidamente creamos en esa carpeta un archivo .gitignore

Tercer paso. Ejecutamos los comandos…

$ cd /Users/usuario/Documentos/Proyectos/indice
$ git init

Cuarto paso. Creamos en esa carpeta un archivo de texto README.md con una presentación de nuestro portal:

# Mi portal de documentación

Una colección más de libros accesible en <https://usuario.github.io>

Nota: cambiar “usuario” por nuestro nombre en GitHub

Quinto paso: creamos un archivo de configuración llamado _config.yml (nótese el subrayado como prefijo). En lugar del formato TOML que usamos con mdBook, el conversor de Github utiliza un formato llamado YML. El contenido del fichero puede ser algo así como:

title: Mi sitio de libros
theme: jekyll-theme-cayman

El tema representa el esquema de colores a aplicar. Podemos saber más sobre los temas de GitHub en esta página

El último paso es redactar la página principal a mostrar. La llamaremos index.md, y GitHub la convertirá en index.html:

# Mi portal de documentación

Una breve presentación.

Indice de libros:

-   [Tutorial mdBook](<https://usuario.github.io/tutorial_mdBook/>)
-   [Otro libro](<https://usuario.github.io/otro_libro/>)

Ya está. En la carpeta tenemos:

• un archivo .gitignore

• un archivo README.md que servirá de presentación a quienes visiten GitHub

• nuestra futura página web en formato markdown, index.md

• el archivo de configuración config.yml

• una carpeta .git con el control de cambios

• podemos añadir alguna imagen y mostrarla añadiendo en el archivo index.md:

  ![](imagen.jpeg)
  

Con todo esto, abrimos GitHub Pages, pulsamos en el menú File > Add local repository, seleccionamos la carpeta, y subimos su contenido creando un nuevo repositorio usuario.github.io (cambiando usuario por nuestro nombre). Seguidamente, entramos en la página web de GitHub, comprobamos que se han subido los contenidos, pulsamos en el icono settings y lo publicamos en GitHub Pages.

Por supuesto, podemos obtener una página de presentación más elaborada explorando las capacidades de Jeckyll, o bien, creando un libro mdBook de una sola página.