Página web estática en GitHub Pages

GitHub Pages es un servicio de alojamiento gratuito que ofrece GitHub. En él se permite alojar páginas web estáticas, esto quiere decir que no se permite ejecutar código como PHP o Python y que, por tanto, tampoco hace uso de base de datos.

El aspecto de sus direcciones URL es http://nombreproyecto.github.io (aunque también puede personalizarse un dominio) y su uso mayoritario está siendo el de crear blogs por usuarios con conocimientos de git o páginas con documentación sobre proyectos. Todo este contenido queda recogido en un repositorio, que al igual que nuestra página, también es público.

Algunos de los ejemplos que GitHub destaca en su página «Ejemplos de GitHub Pages» son:

• Bootstrap, el popular framework para crear webs responsive que combina HTML, CSS y JavaScript.
• React, la librería JS creada por Facebook.
• Jekyll, el generador de plantillas HTML estáticas frecuentemente utilizado en GitHub Pages.

En la página oficial de GitHub Pages encontramos una sencilla guía de cómo crear nuestra página web estática, adaptándose según el cliente git que utilicemos (terminal, GitHub para Windows o GitHub para Mac), en nuestro caso utilizaremos git mediante la terminal de comandos.

¿Cómo puedo crear una página en GitHub Pages?

GitHub Pages nos ofrece dos maneras de crear una página web estática en sus servidores. Una de ellas mediante la creación de un repositorio con nuestro nombre de usuario en GitHub y la otra, creando una rama gh-pages de nuestro repositorio.

Páginas de usuarios u organizaciones con el generador automático de paginas

Estas páginas se alojan en un repositorio especial dedicado a los archivos de GitHub Pages. La rama master será en la que se trabajará y publicará el sitio web.

Solo puede utilizarse nuestro propio nombre de usuario o el nombre de la organización para crear una página de usuario u organización. Por ejemplo, un repositorio con el nombre michaeljackson.github.com si nuestro nombre de usuario es EvaristoGZ no construirá ningún sitio en GitHub Pages.

Imagen explicativa de cómo crear tu repositorio para publicar en GitHub Pages.

Los pasos a seguir, indicados en la imagen, son:

1. Identifícate con tu cuenta en GitHub.com y pulsa sobre el icono con el símbolo más. Luego pulsa sobre «New repository«.
2. Escribe tu nombre de usuario seguido de .github.io
3. Describe el nuevo repositorio o nuevo proyecto. Información sobre los autores, breve resumen, autores…
4. Crea el repositorio con un archivo README ya creado, en el que incluya la descripción.
5. Pulsa «Create repository» para crear tu página estática.

Si intentamos acceder a la recién creada http://evaristogz.github.io nos aparecerá un error 404 con el mensaje File not found. Si hemos realizado alguno de estos pasos de manera errónea GitHub nos devolverá un error 404 acompañado del mensaje: There isn’t a GitHub Pages site here.

Automáticamente accedemos a nuestro repositorio creado, allí pulsamos sobre Settings para iniciar la construcción de nuestra página estática y comprobar su funcionamiento.

Podemos comprobar que GitHub lo reconoce como una página que será publicada en github.io y nos da la opción de actualizar nuestro sitio con HTML o Jekyll, o con el generador automático de páginas.

Con el generador automático de páginas, ahorraremos trabajo y podremos modificar el contenido con etiquetas HTML o formato markdown.

Ejemplo del generador de páginas estáticas de GitHub.

Podemos añadir un código de Google Analytics para hacer un análisis de nuestros visitantes y elegir una plantilla facilitada por GitHub Pages para nuestra página estática.

Modificando el contenido autogenerado

Ahora toca clonar el repositorio y realizar las modificaciones mediante la terminal de comandos.

Tras instalar git y añadir nuestra clave SSH pública a GitHub, accedemos a nuestro repositorio en GitHub y en la parte inferior derecha copiamos el campo «SSH clone URL».

En una terminal de comandos creamos la carpeta para nuestros repositorios y ejecutamos git clone git@github.com:EvaristoGZ/evaristogz.github.io.git en mi caso.

Ahora, con el editor de texto nano podemos modificar los archivos de nuestra GitHub Pages. Para actualizarlo en nuestro repositorio de GitHub debemos añadir los archivos modificados con git add archivo1.html archivo2.css y añadirles un comentario a los cambios realizados con git commit -a -m "Texto descriptivo". Por último, con git push enviar los cambios al repositorio de GitHub.

Si hay algún cambio en el repositorio origen (en GitHub) que no esté reflejado en nuestro repositorio local, debemos utilizar el comando git pull el cual es recomendable ejecutar antes de cualquier modificación.

Los cambios no se ven reflejados de manera instantánea.

Páginas de proyecto con Jekyll y formato markdown

Las páginas de proyecto de GitHub Pages se mantienen en el mismo repositorio que el proyecto. Estas se realizan haciendo una rama huérfana llamada gh-pages en el repositorio y podemos hacerlo de manera segura clonando el repositorio de nuestro proyecto.

En mi caso, utilizaré el del proyecto tuitgenerator para realizar una página estática con algo de Jekyll. Por ello, utilizaré el comando git clone git@github.com:EvaristoGZ/tuitgenerator.git. Después creamos una rama huérfana con git checkout --orphan gh-pages.

Si ejecutamos git status observamos que los archivos que estaban en la rama master no se han borrado. El sistema git los marca como si fueran nuevos archivos y los añadiría en un próximo commit a nuestra rama gh-pages. Así pues, eliminamos los archivos de este repositorio situándonos dentro de él y ejecutando git rm -rf .

Seguidamente, necesitaremos de una plantilla para realizar nuestra página estática con funciones de Jekyll. Buscando plantillas gratuitas escritas en HTML5 y Responsive Design di con «Enginery«.

Tras copiar los archivos en el directorio y repositorio tuitgenerator, elimino aquellos de los cuales no voy a hacer uso y adapto los ficheros con los que me quedo. De esta manera, mantengo versiones editadas de index.html, about.html y style.css, incluyendo las imágenes para no romper demasiado el diseño por ahora.

Si lo deseamos, podemos comprobar el diseño y que todas las rutas están correctamente antes de realizar ningún otro cambio. Una vez comprobado, creamos el directorio _layouts donde se insertan los templates de Jekyll (en este caso index.html y about.html).

Estructura final de la rama gh-pages de tuitgenerator.

Los templates ubicados en _layouts se caracterizan porque tienen variables declaradas entre dobles llaves: {{variable}}. La mayoría de estas variables se escriben en las cabeceras de los archivos markdowns, donde se especifica el template que debe utilizar y el valor de las variables de las cuales se debe hacer uso.

Como ejemplo, este es el archivo sobre-el-proyecto.md:

En layout debe llamarse al fichero que queremos utilizar como plantilla/template, este debe estar en _layouts. El resto son variables que hemos insertado en el template (anteponiéndole page.). Estas variables permiten el uso de etiquetas HTML, de modo que podemos decir que el subtitle esté en cursiva de esta manera: <i>Página de prueba para Implantación de Aplicaciones Web</i>.

Bajo la cabecera escribimos con total libertad el contenido con formato markdown.

Estructura del código HTML y las variables de Jekyll utilizadas.

Resultado de las variables utilizadas en el archivo sobre-el-proyecto.md que cargan sobre el template about.html

La ventaja es que en cada template podemos utilizar distintas estructuras, como en el caso del index.html e index.md, donde cada box lleva una variable para su título y su descripción.

Variables de Jekyll utilizadas en el index.md

Las modificaciones de los ficheros las he realizado con el editor de texto Sublime Text 2, más ágil para tratar código. Asimismo, los cambios han sido comentados y subidos a la rama gh-pages con git.

Para finalizar, os dejo una serie de enlaces así como repositorios y resultados:

• Repositorio evaristogz.github.io
• Página estática creada con el generador de páginas estáticas de GitHub Pages.
• Rama gh-pages del repositorio tuitgenerator.
• Página de proyecto tuitgenerator con Jekyll y markdown.
• Publicar una página web en GitHub Pages por José Domingo.