Primer proyecto

En el capítulo anterior hemos creado una carpeta para nuestro primer proyecto y un script verificar_mdbook.sh para comprobar que tenemos acceso al programa conversor mdbook. Ponemos este script en una subcarpeta llamada acciones. Por ahora tenemos:

miProyecto/
  └── acciones/
      └── verificar_mdbook.sh

Crear embrión de estructura

mdBook cuenta con un subcomando init que crea una estructura básica de proyecto. Abrimos un Terminal de comandos y ejecutamos:

$ cd /Users/usuario/Documentos/Proyectos/miProyecto
$ ../herramientas/mdbook init

Estamos pidiendo que se ejecute el programa mdbook que se encuentra en la carpeta herramientas/ dentro de la carpeta padre de la actual, en la que nos hemos situado con el comando cd

Si todo va bien, se inicia un diálogo interactivo en la ventana del Terminal de comandos:

Do you want a .gitignore to be created? (y/n)

Nos está preguntando si queremos crear, entre otras cosas, un archivo llamado .gitignore. Contendrá la lista de archivos que no queremos subir al servidor web una vez que mdBook haya generado el resultado final. Podemos teclear:

… y pulsamos enter. Seguidamente se nos pregunta por el título del libro:

What title would you like to give the book?

y contestamos con algo así como:

Mi primer libro

… y pulsamos enter. Finalmente, si todo va bien, veremos:

INFO Creating a new book with stub content

All done, no errors...

Y ya está. Teníamos una carpeta de proyecto con una subcarpeta acciones y ahora tenemos:

miProyecto/
  ├── acciones/
  │   └── verificar_mdbook.sh
  │
  ├── book.toml
  ├── .gitignore
  │
  ├── book/
  └── src/
      ├── chapter_1.md
      └── SUMMARY.md

Se han añadido dos subcarpetas:

book es un nuevo directorio vacío. Es donde mdBook va a poner el libro final, formado por archivos hmtl, css, javascript, etcétera, listo para subir al servidor web.
src es donde nosotros vamos a poner nuestros archivos fuente (sources), en formato markdown. Nótese que llevan el sufijo .md

Se han añadido cuatro ficheros “plain text”:

miProyecto/.gitignore. Lista de archivos que no se van a subir al servidor web. El punto que se usa como primer carácter del nombre indica que se trata de un archivo oculto en el caso de sistemas Linux o Mac. En Windows lo veremos tal cual.
miProyecto/book.toml. Contiene las opciones de configuración del proyecto.
miProyecto/src/chapter_1.md. Primer capítulo del libro. Los textos en formato markdown llevan el sufijo “.md”

Podemos añadir tantos archivos .md como queramos, y ponerlos en la carpeta src.
miProyecto/src/SUMMARY.md. Contiene el contenido de la barra lateral de navegación, con la lista de capítulos.

Primer contenido

Vamos a cambiar el nombre del fichero chapter_1.md. Le llamaremos capitulo1.md. Lo abrimos con el editor de textos y vemos el contenido generado automáticamente:

# Chapter 1

Introducimos un texto cualquiera:

# Capítulo 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod 
tempor incididunt ut labore et dolore magna aliqua. 
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut 
aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 
voluptate velit esse cillum dolore eu fugiat nulla pariatur. 
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia 
deserunt mollit anim id est laborum.

La primera línea de texto va precedida por un símbolo #. Ya hemos visto que, en el formato markdown, estos párrafos se muestran como título del capítulo, con un tipo de letra más grande. El resto se verá como texto regular.

Guardamos los cambios, creamos un par de archivos más en la carpeta src, y modificamos el archivo SUMMARY.md

# Summary

- [Capítulo 1](capitulo1.md)
- [Capítulo 2](capitulo2.md)
- [Capítulo 3](capitulo3.md)

Cada entrada de la lista muestra un enlace en la barra lateral:

- [Texto a mostrar en el enlace](archivo.md)

Se asume la carpeta src. Podemos poner los archivos en una subcarpeta dentro de src

- [Capítulo 1](docs/capitulo1.md)

El archivo de configuración

Además de reescribir el primer capítulo, añadir otros capítulos, y modificar el archivo SUMMARY.md, podemos revisar el fichero de configuración book.toml:

[book]

title = "Mi primer libro"
authors = ["Pedro"]
language = "en"

Por ahora, lo dejaremos como está. Lo veremos más adelante. Podríamos cambiar la línea:

language = "es"

Generar el sitio web

Con este embrión inicial, vamos a crear nuestro sitio web. Abrimos el terminal de comandos y ejecutamos:

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

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 pasándole dos argumentos:

la operación a realizar:
- clean borra el directorio especificado. De esta forma eliminamos versiones del libro generadas anteriormente.
- build construye el libro
el directorio de destino se llamará book (aunque podemos darle otro nombre):
```
--dest-dir book
```

Visualizar el libro generado

Examinamos la carpeta generada book. Encontraremos:

Un archivo index.html que actúa como página principal
Un archivo .html por cada capítulo
Un archivo toc.html con la Tabla de Contenidos que se visualiza en la barra lateral.
Un archivo print.html que se usa al pulsar en el icono Imprimir Libro.
Un archivo 404.html que se muestra cuando no se encuentra una página.
Varios archivos css con las hojas de estilo generadas por mdBook
Archivos .js con la programación de acciones varias en lenguaje JavaScript
Imágenes, fuentes de letra, etcétera

Pulsamos sobre el archivo index.html y veremos en el navegador nuestro primer libro en su estado embrionario (en este ejemplo no he incluido mas que un capítulo en el archivo SUMMARY.md).

Todo lo que tendríamos que hacer ahora es subir el contenido de la carpeta book (o el nombre que le hayamos dado ) a un servidor, y configurarlo para que los accesos del público visualicen en primer lugar el archivo index.html. Pero eso lo veremos al final de este cuaderno.