Noticias de Stack Builders

Ideas y notas de nuestro equipo


Juan Pedro Villa

Dr. Hakyll: Crea una página de Github con Hakyll y CircleCI


(Traducción de Cristhian Motoche)

Hakyll es una librería y programa de Haskell para crear sitios web estáticos, tales como blogs sencillos. Los sitios hechos con Hakyll se configuran en Haskell de forma similar a xmonad. Además, usan Pandoc, lo que significa que el contenido puede ser escrito en lenguajes como Markdown y LaTeX.

Empezar a usar Hakyll es fácil gracias a los tutoriales y ejemplos oficiales. Además, hay varias entradas de blogs sobre cómo construir y publicar un sitio web con Hakyll:

Luego de utilizar servicios como Blogger y WordPress.com, y revisar herramientas como Jekyll (el cual inspiró a Hakyll), finalmente decidí crear un blog con Hakyll, GitHub Pages, y CircleCI. Aquí están los pasos que seguí:

Configurar Git y GitHub

GitHub Pages te da un sitio de usuario (y uno de organización) y un sitio de proyecto para cada uno de tus repositorios. La diferencia más relevante entre los sitios de usuario y proyecto es que GitHub utiliza la rama master para publicar sitios de usuario y la rama gh-pages para publicar sitios de proyecto.

Para crear un sitio de usuario u organización:

  • Crea un repositorio username.github.io, donde username es tu nombre de usuario u organización en GitHub

  • Crea un repositorio de Git vacío para tu sitio, realiza un commit, y haz push:

    $ mkdir username.github.io/
    $ cd username.github.io/
    $ git init
    $ git commit --allow-empty -m "Create master branch"
    $ git remote add origin git@github.com:username/username.github.io.git
    $ git push -u origin master

    La rama master es utilizada por GitHub para publicar tu sitio. Este es solo un commit vacío para crear la rama. Cuando tu sitio esté listo, puedes hacer push a master manualmente, pero la idea es tener un servicio de integración continua que haga eso por ti.

  • Crea una rama huérfana denominada hakyll para el contenido de tu sitio:

    $ git checkout --orphan hakyll

    La rama hakyll contendrá la configuración de tu sitio y su contenido.

  • Añade tu repositorio de GitHub como un submódulo de Git en _site, realiza un commit, y haz push:

    $ git submodule add git@github.com:username/username.github.io.git _site
    $ git commit -m "Create hakyll branch"
    $ git push -u origin hakyll

    GitHub Pages no está diseñado para trabajar inmediatamente con herramientas como Hakyll. Ya que Hakyll genera tu sitio en un directorio llamado _site, puedes utilizar este directorio para actualizar el sitio publicado por GitHub.

Para crear un sitio de proyecto para un repositorio (repository) existente de GitHub, utiliza gh-pages en lugar de master:

  • Crea una rama huérfana denominada gh-pages, realiza un commit, y haz push:

    $ git clone git@github.com:username/repository.git
    $ cd repository/
    $ git checkout --orphan gh-pages
    $ git rm -rf .
    $ git commit --allow-empty -m "Create gh-pages branch"
    $ git push origin gh-pages
  • Crea una rama huérfana denominada hakyll para el contenido de tu sitio, añade el repositorio de GitHub como un submódulo en _site, realiza un commit, y haz push:

    $ git checkout --orphan hakyll
    $ git rm -rf .
    $ git submodule add git@github.com:username/repository.git _site
    $ git commit -m "Add hakyll branch"
    $ git push -u origin hakyll

En las siguientes instrucciones se asume que estás creando un sitio de usuario (u organización). Si estás creando un sitio de proyecto, las instrucciones son muy similares, pero utiliza la rama gh-pagesen lugar de master.

Configurar Hakyll

La forma más sencilla para configurar Hakyll es utilizar el programa hakyll-init como está descrito en las instrucciones de instalación. Básicamente:

  • Instala Hakyll:

    $ cabal install hakyll
  • Crea el sitio de ejemplo:

    $ hakyll-init .
  • Configura y construye:

    $ cabal configure
    $ cabal build
  • Genera el sitio:

    $ cabal run build

    Realiza una vista previa del servidor:

    $ cabal run watch

    Y ve a http://localhost:8000/.

  • Si cambias la configuración de tu sitio, vuelve a construirlo con:

    $ cabal run clean
    $ cabal run build

    O:

    $ cabal run rebuild

Como otra opción, utiliza el proyecto de ejemplo de Dr. Hakyll. Es un sitio de Hakyll que puede ser usado como un complemento para el sitio de ejemplo de Hakyll:

(Mira el blog de Bryn Keller's para un ejemplo de un sitio estático creado con Hakyll y el ejemplo de blog de Bootstrap.)

Una vez que tu sitio esté listo, añade y confirma todos los cambios (excepto _cache, _site, y otros archivos ignorados de Haskell):

$ git add --all
$ git commit -m "Configure Hakyll"

Ahora puedes hacer un push de los cambios o esperar hasta que CircleCI sea configurado:

$ git push origin hakyll

Configurar CircleCI

Para configurar CircleCI, ve a tu repositorio de GitHub, añade una clave de usuario a las claves SSH en la configuración de tu proyecto, y asegúrate de que esté seleccionada por defecto:

Ahora, crea un archivo circle.yml y añade tu configuración:

  • Añade una versión de GHC a la configuración de la máquina:

    machine:
    
      ghc:
        version: 7.8.4

    O:

    machine:
    
      ghc:
        version: 7.10.1
  • Reemplaza la sección de dependencias para instalar las dependencias y configurar el paquete:

    dependencies:
    
      override:
        - cabal update
        - cabal sandbox init
        - cabal install --only-dependencies -j
        - cabal configure
  • Reemplaza la sección de pruebas para que simplemente se construya el paquete:

    test:
    
      override:
        - cabal build

    Si el programa compila con éxito, CircleCI debería inicializar y actualizar el submódulo de _site, y cambiar a la rama master (o gh-pages). Adicionalmente, debería generar tu sitio:

      post:
        - git submodule init
        - git submodule update
        - cd _site/ && git checkout master
        - cabal run build
  • Añade una sección de despliegue para actualizar tu sitio cada vez que realizas un push a la rama de hakyll. Primero, realiza un push de todos tus cambios en _site a master utilizando la fecha y hora actual como referencia en el mensaje del commit. También, añade [ci skip] para hacer que CircleCI salte la construcción en master:

    deployment:
    
      production:
        branch: hakyll
        commands:
          - git config --global user.email circleci@circleci
          - git config --global user.name CircleCI
          - cd _site/ && git status
          - cd _site/ && git add --all
          - cd _site/ && git commit -m "Update (`date '+%F %T %Z'`) [ci skip]"
          - cd _site/ && git push origin master

    Segundo, actualiza el submódulo en la rama hakyll. Un submódulo es una referencia estática a un commit específico en un repositorio. En este caso, la rama hakyll tiene una referencia a un commit en la rama master. Debido a que la rama master fue actualizada, la referencia en hakyll debe ser actualizada para apuntar hacia el último commit. CircleCI solo debería añadir _site y realizar un push. De nuevo, añade [ci skip] al mensaje del commit para evitar construir todo nuevamente. Para mayor información sobre los submódulos de Git, mira la referencia o los Git submodules de Nicola Paolucci.

          - git status
          - git add _site/
          - git commit -m "Update _site (`date '+%F %T %Z'`) [ci skip]"
          - git push origin hakyll
  • Si quieres utilizar tu zona horaria con el comando date, añádelo a la configuración de la máquina:

    machine:
    
      ...
    
      timezone:
        America/Guayaquil

    O directamente al comando date:

    TZ=America/Guayaquil date '+%F %T %Z'

Finalmente, realiza un push de tus cambios:

$ git add circle.yml
$ git commit -m "Configure CircleCI"
$ git push origin hakyll

Una vez que CircleCI haya construido tu sitio, habrás terminado. Ve a http://username.github.io.

Notas

Creo que Hakyll es un excelente generador de sitios estáticos. Los ejemplos y tutoriales lo hacen aún mejor. Y es Haskell. Sin embargo, hay algunas cosas que no funcionan inmediatamente que vale la pena mencionar:

Comentarios

Por defecto, no hay comentarios en un blog de Hakyll. Hay varios ejemplos de sitios orgullosamente generados por Hakyll que utilizan servicios como Disqus, lo cual es suficientemente bueno para mí.

Borradores

Por defecto, Hakyll no tiene manera de trabajar con borradores. Pero puedes configurar tu sitio para que haga eso. Para información detallada sobre una forma para hacerlo, mira Drafts in Hakyll por Jorge Israel Peña.

Ya que los sitios de Hakyll pueden ser utilizados con Git y GiHub, mi solución favorita para los borradores es simplemente crear una rama separada y utilizar un pull request para cada entrada. Puedes previsualizar tu sitio, pero solo incluirá el borrador si realizas un merge con la rama hakyll.

comments powered byDisqus

¿Tienes lo necesario para ser un Stack Builder?