Preparando el libro

En capítulos anteriores vimos como crear un directorio para alojar los archivos que forman el libro final, listo para subir a un servidor web. El script era algo así como:

cd /Users/usuario/Documentos/Proyectos/miProyecto
../herramientas/mdbook clean --dest-dir libro
../herramientas/mdbook build --dest-dir libro

El primer comando nos sitúa en el directorio principal del libro. Los otros dos comandos acuden al directorio padre, subdirectorio /herramientas y ejecutan el programa mdbook indicando el directorio de destino, libro.

La operación clean borra el directorio especificado si ya existiera. De esta forma eliminamos versiones del libro generadas anteriormente.

El resultado final es una carpeta libro con una colección de archivos en formato HTML, CSS, imágenes, etcétera. Todo este paquete puede subirse a cualquier servidor web configurado para admitir páginas de tipo “estático”, es decir, archivos que se descargan y visualizan en nuestro navegador sin sufrir modificaciones.

Yo utilizo GitHub como repositorio de libros, y hago uso de un servicio llamado GitHub Pages, que permite visualizar la documentación en forma de sitio web.

Acerca de Git

GitHub es un servicio destinado tanto a proyectos personales como a los desarrollados en grupo, y uno de sus componentes más importantes es el control de modificación de ficheros y versiones de los contenidos subidos. Para gestionar todo esto, necesitamos instalar en nuestro ordenador personal un programa llamado Git.

Git es un software open source, concebido inicialmente por Linus Torvalds, el creador del sistema operativo Linux. Podemos comprobar que lo tenemos instalado abriendo un terminal de comandos e introduciendo:

$ git --version

Si necesitamos instalarlo en nuestro equipo, podemos ir al repositorio de software de nuestro sistema operativo, o bien descargarlo de la página web oficial de Git

Git es un software concebido para profesionales, complejo y con muchas funcionalidades que posiblemente no necesitaremos. En todo caso, en esta página tenemos un libro sobre la materia, de libre acceso y descarga

Archivos a evitar

Una de las piezas de Git es el control de archivos que no queremos subir al servidor. Por ejemplo, yo utiliza un Mac para desarrollar mi documentación, y este sistema operativo crea automáticamente en todas las carpetas un archivo oculto llamado .DS_Store (Desktop Services Store) con las preferencias de visualización de la carpeta, posición de los iconos, tamaño de la ventana, etc. Es equivalente al fichero thumbs.db de Windows, está presente en muchas de nuestras carpetas, y no es algo que queramos subir al servidor web.

Para evitarlo, creamos un archivo “plain text” llamado evitar, con el siguiente texto (para un Mac):

_DS_Store
otro_archivo1
otro_archivo2

… etcétera. En el script de compilación, añadimos un comando cp (copy):

cd /Users/usuario/Documentos/Proyectos/miProyecto
../herramientas/mdbook clean --dest-dir libro
../herramientas/mdbook build --dest-dir libro
cp evitar libro/.gitignore

lo que significa “copiar el archivo evitar a la carpeta libro y darle el nombre .gitignore”. Recordemos que, en Mac/Linux, los archivos con un punto de prefijo son archivos ocultos.

Control de versiones

Una vez creado el contenido final a subir, tenemos que añadir el control de versiones Git. Abrimos un Terminal de comandos y ejecutamos:

cd /Users/usuario/Documentos/Proyectos/miProyecto
cd libro
git init

… es decir, nos situamos en la carpeta principal del proyecto, saltamos a la carpeta generada que tiene el contenido del libro, y creamos un control de versiones con el comando git init. Esto crea una subcarpeta oculta .git

¿Como visualizar archivos ocultos?

---

Todos los sistemas operativos suelen tener un explorador de ficheros con una opción de menú Ver > Elementos ocultos. Cada sistema es un mundo. En un Mac, por ejemplo, se activa pulsando la combinación de teclas command ⌘ + mayúsculas ⇧ + .

El comando git solo es necesario la primera vez que creamos el libro. Pero mdBook tiene un “gazapo”. Cada vez que ejecutamos mdbook clean, se borra todo el contenido de la carpeta de resultados, incluyendo esa subcarpeta oculta .git. Para solucionarlo, vamos a moverla a un lugar seguro en el script de creación del contenido final. Añadimos al script el siguiente comando:

mv libro/.git .

Movemos la carpeta libro/.git al directorio actual (en el que nos hemos situado al principio del script) representado por un punto . Con esto tenemos:

cd /Users/usuario/Documentos/Proyectos/miProyecto

mv libro/.git .

../__mdbook_tools/mdbook clean --dest-dir libro
../__mdbook_tools/mdbook build --dest-dir libro

cp gitignore libro/.gitignore
mv .git libro

Terminamos con un comando que recupere el control de versiones moviendo de nuevo la subcarpeta .git a la carpeta libro.

El archivo README

Los proyectos alojados en GitHub suelen incluir un archivo markdown README.md que se utiliza como presentación para quienes visiten las páginas de GitHub con el propósito de examinar el contenido “en bruto”. Podemos crear este archivo en la carpeta principal de nuestro proyecto:

# Mi maravilloso libro

Una descripción a manera de presentación

Y lo incluimos entre los contenidos a subir al servidor. El script queda así:

cd /Users/usuario/Documentos/Proyectos/miProyecto

mv libro/.git .

../__mdbook_tools/mdbook clean --dest-dir libro
../__mdbook_tools/mdbook build --dest-dir libro

cp README.md libro/README.md
cp gitignore libro/.gitignore
mv .git libro

¡Importante!. No debemos poner el archivo README.md en la carpeta src, ya que sería considerado como una página más del libro. De hecho, mdBook la consideraría como página principal, y le daría el nombre index.html.