Exportar una wiki de GitHub a HTML, fácil y rápido

Las wikis de Github te permiten mantener documentación relevante del proyecto en el mismo servicio, por lo que resultan bastante prácticas y cómodas de usar, pero si necesitas compartir esa documentación sin dar acceso al código podrías generar una versión HTML con muy poco esfuerzo.

En primer lugar clona tu wiki como repositorio: cada wiki ya es un repositorio de git con su historial de versiones y todo; la URL para clonarla está en la barra lateral derecha, bajo el listado de páginas.

Para convertir las páginas de la wiki en archivos HTML puedes usar Harp, un “servidor de webs estáticas con pre-procesamiento incluído”: en pocas palabras, te permite escribir código en Markdown, LESS, CoffeeScript, EJS y visualizar como HTML, CSS, Javascript, definir plantillas y partials… y como cada página de la wiki es un archivo Markdown, estamos de suerte.

Harp es un chiche en sí mismo y de verdad merece una explicación más profunda de todas las posibilidades que tiene, pero dejaré eso para otro post.

Puedes definir plantillas con EJS o Jade; en lo personal prefiero la primera alternativa ya que es mucho más similar a HTML y por lo tanto con una curva de aprendizaje muy elevada. Puedes utilizar algo muy sencillo como lo siguiente, con el nombre de _layout.ejs:

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <title>Documentación de mi proyecto</title>
    <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.1/css/bootstrap.min.css">
</head>
<body>
    <div class="container">
        <%- yield %>
    </div>
</body>
</html>

En este caso estamos usando simplemente los estilos predeterminados de Bootstrap sin mayor modificación. La parte importante es la que indica <%-yield %> ya que señala el lugar donde se inserta el contenido de cada archivo Markdown.

Luego, en la carpeta donde tienes los archivos y la plantilla, debes ejecutar el siguiente comando para compilar cada archivo en un HTML: harp compile . carpeta-html

¡Listo!