Jekyll+GitHub Pages

Este sitio está creado con la tecnología de GitHub Pages. Tratándose de GitHub, está basado en Ruby, en concreto en el gem Jekyll. Tras estudiarlo un poco me gustó mucho por distintos motivos y me animé a poner en marcha el proyecto. Llevo años acumulando información en un Dokuwiki, que me sigue encantando, pero me gusta mucho más el formato Markdown que casi se puede considerar un estándar ya. Además hace tiempo que tenía la intención de hacer pública la mayoría de la información que en Dokuwiki mantenía. El haber encontrado Jekyll ha desencadenado el proceso de migración/publicación de estos apuntes.

El sitio se genera simplemente creando un nuevo repositorio dentro de la cuenta GitHub teniendo el nombre un formato determinado, concretamente username.github.io, siendo username nuestro identificador de usuario en GitHub. Así de sencillo. A partir de entonces todo lo que el repositorio contenga será servido con base a la URL http://username.github.io

Al ser un repositorio git (guía sencilla para git), los cambios en la página se hacen mediante commits en el propio repositorio. GitHub Pages soporta además el mencionado Jekyll, lo que nos permitirá dar estructura al sitio, gestionando los menús, las páginas y los posts del blog. Los documentos escritos en Markdown (existe la opción de trabajar también en Textile y HTML) resultan con un estilo homogéneo y fácil de mantener. Con Jekyll tenemos tres de las cosas que más me gustaban de Dokuwiki, como son que se incluye un sistema de remarcado de sintaxis en los listados de código incrustados en los documentos (cosa que es habitual en la clase de documentación que manejo), evitamos utilizar una base de datos y finalmente el código de los documentos no resulta alterado por editores WYSIWYG. Como novedad frente a Dokuwiki, el sitio resultante es estático, es decir, todo se termina compilando en HTML puro, con lo que obtenemos velocidad y seguridad.

Las instrucciones oficiales con detalle para montar el sitio en GitHub Pages con soporte Jekyll están aquí. El proceso paso a paso en mi caso fue como sigue:

Los requerimientos previos son tener instalado Ruby 1.9.3 como mínimo (yo utilicé el que viene empaquetado en Ubuntu, es decir sudo apt-get install ruby), RubyGems y Bundler (lo instalamos con RubyGems, es decir sudo gem install bundler).
Creamos el repositorio en GitHub. Como hemos dicho el nombre tendrá que ser nuestro identificador de usuario más el sufijo .github.io. No sólo eso, si estamos haciendo una página de usuario (también existe la posibilidad de crear una página de proyecto), tendremos que trabajar obligatoriamente con el branch master. A partir de ahora voy a indicar mi nombre de usuario, es decir eduardofilo en lugar de username para hacerlo más realista.
Clonamos el repositorio en nuestra máquina para trabajar en local y seleccionamos el branch mencionado (aunque en realidad no es necesario porque es el predeterminado):
1 2 3
$ cd ~/git $ git clone https://github.com/eduardofilo/eduardofilo.github.io.git $ git checkout master
Instalamos Jekyll. Bueno, en realidad instalamos github-pages que lo lleva incluido como dependencia:
1
$ gem install github-pages
Generamos la estructura del sitio con Jekyll. En este paso el directorio donde vamos a generar la estructura deberá estar vacío o se producirá un error. Si existían ficheros (como el README.md que suele generar GitHub), tendremos que sacar temporalmente esos ficheros del directorio y devolverlos posteriormente:
1 2
$ cd ~/git/eduardofilo.github.io $ jekyll new .

Creamos el fichero Gemfile que gestionará las dependencias del proyecto:

# ~/git/eduardofilo.github.io/Gemfile
source 'https://rubygems.org'
gem 'github-pages'

Generamos un fichero .gitignore para que no ser carguen en GitHub un fichero y un par de directorios que se generan dinámicamente a partir del resto:
1 2 3 4
# ~/git/eduardofilo.github.io/.gitignore _site .sass-cache Gemfile.lock
Ejecutamos el siguiente comando para que encajen todas las dependencias:
1 2
$ cd ~/git/eduardofilo.github.io $ bundle install
Levantamos el servidor web de desarrollo para ir observando los cambios en el sitio mientras generamos o modificamos los ficheros, por defecto estará accesible a través de la URL: http://localhost:4000
1 2
$ cd ~/git/eduardofilo.github.io $ bundle exec jekyll serve

Y ya está. A partir de ahora tocará retocar el sitio para dejarlo a nuestro gusto. En mi caso he creado directorios para las distintas secciones de documentación que manejo (Desarrollo, Sistemas, Proyectos y Varios). Dentro de estos directorios mantengo documentos en Markdown que luego enlazo desde el fichero que se sirve de forma predeterminada (index.md aunque también puede ser el más clasico index.html). La función más habitual de Jekyll es la de gestionar una estructura de Blog. También la he aprovechado, manteniendo los ficheros en el subdirectorio _posts. En este caso los ficheros tienen que tener una nomenclatura especial, ya que de su nombre sale la fecha del post y su URL. En ambos tipos de documentos, es importante el sistema de metainformación llamado FrontMatter. Todos los documentos llevan una pequeña sección al comienzo delimitada por dos líneas de tres guiones en formato YML. Es recomendable leer la documentación sobre su uso ya que tiene múltiples efectos sobre el funcionamiento de Jekyll. De hecho los documentos que no lleven esta cabecera YML no serán procesados por Jekyll (esto puede servir para dejar de lado algunos ficheros como por ejemplo el README.md en mi caso).

Para no tener problemas, conviene ajustarse a las versiones de los componentes que utiliza GitHub, pero al menos en mi caso, sin haberlo hecho (ya de partida uso Ruby 1.9.3 en mi ordenador) no he observado diferencias entre el servidor en desarrollo y lo servido finalmente por GitHub. Si se tienen problemas o se quiere ser más riguroso, estas son las versiones que hay que tener en cuenta: https://pages.github.com/versions/

Como curiosidad decir que el directorio _site que hemos ignorado en git (al incluirlo en .gitignore) es donde Jekyll genera todo el contenido estático que termina sirviendo (lo que de hecho sirve GitHub). Por último dejar aquí la guía de GitHub sobre la variante de Markdown concreta que ellos soportan. Directamente no es la que trae Jekyll de serie, aunque en mi sitio he ido haciendo ajustes para que se parezca lo más posible.

Para ver y seguir cómo se he hecho el proceso en este sitio, el código de todo se encuentra en: https://github.com/eduardofilo/eduardofilo.jekyll