El generador de documentación
mdBook

Bienvenido a mis apuntes sobre mdBook. Se trata de un software para crear libros en formato web, como es el caso de este propio cuaderno.

mdBook ha sido desarrollado por la comunidad de programadores del lenguaje Rust, con el propósito principal de desarrollar la documentación de ese lenguaje, aunque puede utilizarse en todo tipo de proyectos.

Algunos ejemplos de libros creados con mdBook:

• Tutorial oficial de Rust
• Novedades entre ediciones de Rust
• Tutorial de mdBook
• Otros ejemplos varios

mdBook es un software alojado en Github, y es de libre descarga y uso.

Para examinar el contenido de este cuaderno, podemos puilsar en los enlaces del panel lateral izquierdo o utilizar la tecla ? para visualizar un resumen de teclas de navegación.

Nota

---

Este tutorial está basado en mi experiencia con mdBook, y lo comparto con quienes, como yo, deseen utilizar este software para desarrollar libros web en general. No lo he concebido para programadores de Rust, quienes pueden profundizar en la materia acudiendo a la guía oficial de mdBook donde descubriran funcionalidades específicas para documentar el lenguaje de programación Rust.

Índice de cuadernos

Anatomía de un libro web

Formatos

mdBook está orientado principalmente a crear libros web en formato HTML, el estándar principal de las páginas que encontraremos en la red. Podemos obtener otros formatos, PDF, ePUB, etcétera, si descargamos e instalamos unos complementos llamados backends. Véase lista

Navegación

Un libro está formado por capítulos, y cada uno es una página web que se muestra por separado. El contenido de cada página suele estar formado por un párrafo que hace de título principal, con letra de mayor tamaño, títulos de secciones (en este cuaderno los mostramos subrayados) y párrafos de texto regular.

El panel lateral es la forma básica de acceder a cada capítulo. Podemos ajustar su tamaño arrastrando el borde con el ratón. El panel solo se muestra si la pantalla es suficientemente ancha. En particular, no se mostrará en dispositivos móviles de pantalla pequeña, siendo sustituido por un menú desplegable al pulsar sobre el icono de las tres barras

Al pie de página, o en los bordes laterales (dependiendo del ancho visualización) suele haber dos botones < > para ir al capítulo siguiente/anterior

Podemos pulsar sobre un párrafo de cabecera de sección para seleccionarla, desplazando el título a la parte superior de la pantalla. Ese párrafo de título será señalado con un símbolo », y en la barra de direcciones del navegador, veremos la URL completa, con el enlace a la sección.

La barra superior

La barra superior de cada página muestra el título del libro. Si desplazamos el contenido del capítulo hacia abajo, la barra se mantiene siempre visible, y pulsando sobre ella, se desplaza la página otra vez hacia el extremo superior.

La barra contiene unos botones de utilidad cuya presencia depende de la configuración de mdBook al generar el libro (podemos ocultar alguno de los botones). Pueden ser:

Búsquedas

Pulsando en el icono de búsqueda en la barra superior, o usando las teclas / o S se abre una caja para introducir textos de búsqueda. A medida que tecleamos el texto a buscar, se va mostrando una lista de resultados.

Podemos pulsar con el ratón en alguna de las entradas de la lista para ir a esa página, o bien la tecla Esc para abandonar. También podemos usar las teclas de flecha ↑ ↓ para desplazarnos por la lista y pulsar enter para seleccionar el elemento resaltado.

Ayuda

Pulsando en la tecla ? se muestra un recuadro emergente con un resumen de teclas de atajo:

mdBook no cuenta con la opción de traducir este mensaje, pero en este cuaderno veremos como manipular el programa para que el texto se vea en español.

Archivos

mdBook genera libros web a partir del contenido de varios archivos de texto, uno por cada capítulo. Básicamente, el proceso pasa por las siguientes fases:

1. En nuestro ordenador personal, creamos una carpeta para cada proyecto.

2. Usando un editor, llenamos esa carpeta con archivos de texto, uno por capítulo. Serán nuestros “ficheros fuente” (source files).

3. mdBook toma esos archivos fuente, construye el sitio web, y pone los ficheros resultantes en una subcarpeta.

4. Finalmente, subimos el contenido de esa subcarpeta a un servidor web, quedando a disposición de quien quiera acceder al libro así publicado.

5. En el futuro, para introducir cambios en el libro, modificamos el archivo fuente en cuestión, y repetimos los pasos tres y cuatro, sobreescribiendo lo que hay alojado en el servidor

Nota:

---

Algunos generadores de libros web permiten editar directamente los contenidos en el servidor; mdBook parece estar más orientado al trabajo de edición en ambiente local.

Archivos de texto

A grandes rasgos, en el mundo de los ordenadores existen dos tipos de ficheros:

• los “binarios”, formados por ceros y unos que representan imágenes, sonido, etc.

• los ficheros de texto, que consisten exclusivamente en una secuencia de caracteres.

Para crear documentación, podemos utilizar dos tipos de programa:

• Editores “Rich text format”, donde los documentos incluyen texto, imágenes, tipografía, y toda clase de elementos gráficos. Típicamente, los ficheros se suelen guardar en formato binario, y se editan con procesadores de texto tipo Microsoft Word o Libre Office.

  

• Editores “Plain text”, que no admiten elementos gráficos ni información añadida sobre estilos de letra. Habitualmente se editan con editores tipo bloc de notas.

  

mdBook crea sitios web a partir de documentos en formato plain text.

Acerca del término “plain text”

---

En algunos manuales técnicos, a los archivos plain text se les llama ficheros de “texto plano”. Realmente no tiene nada que ver con que sea plano o redondo. La traducción correcta sería “texto sin más añadidos”, “texto simple” o “texto sin formato”. Ver Wikipedia.

Editores de plain text

Para editar archivos plain text, Windows proporciona, desde sus origenes, un pequeño editor llamado “Bloc de notas”. Los ordenadores Mac vienen con un sencillo editor llamado TextEdit, que admite archivos en formato RTF (por defecto) o de texto simple. Debemos cambiar la configuración del editor para que se guarden como texto sin formato.

Los sistemas Linux suelen proporcionar de serie uno o varios editores, pero eso depende de la distribución que tengamos instalada, Ubuntu, Fedora, etc.

Si no nos convence el editor que se suministra por defecto con nuestro sistema operativo, tenemos cientos de alternativas a nuestra disposición en la red. Véase Wikipedia

Archivos con marcas

Existe un caso especial de archivos “plain text”. Son aquellos que escribimos añadiendo anotaciones con información sobre el formato de presentación. A estas anotaciones se las denomina “marcas”.

Cuando acudimos a un sitio web, cada página que se descarga es en realidad un archivo en formato plain text, con unas marcas que proporcionan al navegador todo lo que necesita saber para establecer el aspecto final de la visualización. Los elementos gráficos (imágenes, etc) son archivos descargados en paralelo.

Veamos a continuación el aspecto que tiene un archivo web tal y como se transmite por la red antes de ser visualizado en el navegador.

Formato HTML

Supongamos, por ejemplo, que una página web muestra el siguiente contenido:

El archivo que se descarga es un plain text que contiene (entre otras cosas) lo siguiente:

Un texto <b>en negrita</b> y este otro <i>en cursiva</i>.

Las marcas de las páginas web se denominan etiquetas, y se delimitan entre dos ángulos < >. El navegador no muestra esas etiquetas en la pantalla, pero las utilizará para determinar el formato de presentación de la página. En nuestro ejemplo:

• La etiqueta <b> indica el comienzo del texto en negrita (bold).
• La etiqueta </b> indica el fin del texto en negrita.
• La etiqueta <i> indica el comienzo del texto en cursiva (itálica).
• La etiqueta </i> indica el fin del texto en cursiva.

Las etiquetas han de respetar unas reglas de sintaxis que se denominan lenguaje de marcas. Existen numerosos lenguajes de marcado. Véase Wikipedia. Las páginas web utilizan una sintaxis denominada HTML, abreviatura de HyperText Markup Language.

En una primera aproximación, se podría decir que, para crear una página web, todo lo que necesitamos es un editor de plain text para crear ficheros de texto que lleven etiquetas HTML. Veamos esto con más detalle.

Anatomía de un archivo HTML

Volvamos a nuestro ejemplo. Supongamos que queremos mostrar lo siguiente en la ventana del navegador:

El contenido del archivo de texto transmitido sería algo así como:

<!DOCTYPE html>
    <html>
        <body>

            <h1>Mi primer documento</h1>
            
            <p>Un texto <b>en negrita</b> 
            y este otro <i>en cursiva</i>.
            </p>

        </body>
    </html>

Para ensayar con el formato HTML, probemos a copiar este texto a nuestro editor plain text. Lo guardamos asignándole un nombre con sufijo .html, por ejemplo, prueba.hmtl

No es necesario que lo copiemos a un servidor web. Con tenerlo en nuestro disco duro, basta. Al hacer doble clic sobre el fichero, el sistema lo identificará como página web (gracias a la extensión .html), y lo abrirá en la ventana del navegador.

Analicemos el contenido de este primer ejemplo. Algunas líneas están sangradas (espaciado a la izquierda) y otras están en blanco. Todo eso es puramente decorativo, y será ignorado por el navegador web. El resultado final sería el mismo si el contenido del archivo fuera:

<!DOCTYPE html><html><body><h1>Mi primer documento</h1>
<p>Un texto <b>en negrita</b>y este otro <i>en cursiva</i>.
</p></body></html>

…pero al usar el editor de textos, resulta más cómodo utilizar un formato que sea amigable.

Veamos ahora el significado de las etiquetas. Todo documento web suele empezar con la etiqueta <!DOCTYPE html>, lo que indica que se trata de un archivo en formato HTML. Las etiquetas <html> y </html> delimitan el contenido del archivo:

<!DOCTYPE html>
    <html>
        contenido del archivo
    </html>

Los diferentes bloques de texto se suelen delimitar con una etiqueta de apertura y una de cierre, que es la misma, pero añadiendo una barra /.

El contenido de una página web puede estar formado por dos secciones:

<!DOCTYPE html>
<html>

  <head>
    Cabecera del documento con información sobre el mismo (opcional)
  </head>

  <body>
    Cuerpo del documento con el texto a mostrar
  </body>

</html>

Los párrafos del documento se colocan en la sección <body>, y cada uno de ellos se delimita entre etiquetas <p> y </p>. El navegador unirá todas las líneas de cada párrafo en una sola, e insertará un espaciado entre párrafos. Es decir, es lo mismo escribir:

<p>Texto del párrafo 1</p><p>Texto del párrafo 2</p>

que

<p>Texto del 
párrafo 1</p>
<p>Texto del párrafo 2</p>

ya que el navegador ignora todo espaciado extra y concatena las líneas de texto, separando visualmente los párrafos, y resultando lo siguiente:

Si sustituimos las etiquetas <p> por <h1>, obtendremos un párrafo de título del documento, mostrado con un tipo de letra especial:

<h1>Mi primer documento</h1>
<p>Párrafo de texto regular</p>

Los párrafos de título pueden establecerse con varios niveles de importancia:

• <h1> ... </h1> para el título principal del documento
• <h2> ... </h2> para títulos de secciones
• <h3> ... </h3> para títulos de subsecciones

… y así sucesivamente, hasta llegar a <h6>. El resaltado (tamaño de letra, etcétera) va de mayor a menor, en función del nivel indicado por la etiqueta.

Estándares web

El formato HTML establece unas reglas de escritura que pueden parecer bastante rigurosas. En realidad han sido concebidas para describir con total exactitud el contenido de una página. Los navegadores suelen ser bastante permisivos, asumiendo algunos valores por defecto, si falta alguna etiqueta, o ignorando las etiquetas mal escritas, sin mostrar ningún mensaje de error.

Tanto el formato HTML como otros estándares de Internet están regulados por el World Wide Web Consortium, autoridad mundial que publica recomendaciones y estándares para asegurar el buen funcionamiento de la web. Este consorcio fue creado en octubre de 1994.

El formato markdown

Redactar un documento en formato HTML puede llegar a ser bastante farragoso, con tanta etiqueta. En su lugar, es costumbre utilizar otros lenguajes de marcas más sencillos.

Para crear un libro web, el formato que vamos a usar para redactar los archivos fuente es Markdown. Siguiendo con nuestro ejemplo, el archivo “fuente” quedaría así:

# Mi primer documento
            
Un texto **en negrita** 
y este otro *en cursiva*.

En formato markdown tenemos lo siguiente:

• Los párrafos se separan con una línea en blanco. No necesitamos etiquetas <p> para delimitarlos.
• Las líneas que forman un párrafo se unen en una sola, como sucede en HTML.
• Los párrafos de título (cabeceras) se marcan anteponiendo un símbolo #.
• El texto se resalta delimitándolo entre asteriscos * (cursiva) o doble asterisco ** (negrita).

Se suele decir que el formato HTML sirve para representar contenidos, y el formato markdown para redactarlos.

De todas formas, este fichero no nos sirve como página web. Necesitamos crear un archivo HTML a partir del fichero markdown. Para ello, necesitamos un conversor, en nuestro caso, mdBook. Tendremos dos archivos:

• mi_pagina_web.md en formato markdown, creado con un editor de plain text. Este será el archivo fuente.

• mi_pagina_web.html generado automáticamente por mdBook a partir del archivo markdown. Es lo que subiremos al servidor web.

Etiquetas HTML en markdown

El uso del formato markdown hace que la tarea de edición del contenido de una página web resulte más simple. Pero tiene sus limitaciones. La sintaxis de markdown no cubre todas las posibilidades que ofrece HTML.

Por ejemplo, supongamos que queremos introducir saltos de línea en mitad de un párrafo:

Nótese que entre líneas no queremos espaciado extra, como sucede entre párrafos. Pero si escribimos en formato markdown:

La canción del pirata:

Con diez cañones por banda,
viento en popa a toda vela,
no corta el mar, sino vuela
un velero bergantín.

En el resultado final, las líneas que forman el párrafo se unirán en una sola:

En los archivos HTML podemos forzar un salto de línea mediante la etiqueta <br>, abreviatura de break:

<p>La canción del pirata:</p>

<p>
Con diez cañones por banda,<br>
viento en popa a toda vela,<br>
no corta el mar, sino vuela<br>
un velero bergantín.
</p>

En un texto markdown, podemos insertar manualmente etiquetas HTML que, con algunas excepciones, serán respetadas (salvo que entren en contradicción con lo generado durante el proceso de conversión):

# La canción del pirata:

Con diez cañones por banda,<br>
viento en popa a toda vela,<br>
no corta el mar, sino vuela<br>
un velero bergantín.

Atributos y estilos

El ejemplo visto en el capítulo anterior es muy sencillo. En el mundo real, los elementos de una página web se suelen configurar para lograr una presentación más sofisticada. Para ello, podemos modificar los atributos de cada elemento, y aplicar reglas de estilo.

Atributos

Todo elemento de una página puede tener unos atributos que se establecen en la etiqueta de apertura:

<!DOCTYPE html>
<html>
    <body>

        <p title="texto de ayuda">
        
        Pasar el ratón sobre este párrafo sin pulsar el ratón, y esperar a 
        que se despliegue automáticamente un texto de ayuda.
        
        </p>

    </body>
</html>
    

Lo que muestra:

Aquí la magia está en la etiqueta de inicio de párrafo:

<p title="texto de ayuda">

en lugar de:

<p>

El atributo title es común a muchos elementos web, y permite mostrar un texto emergente cuando se pasa el ratón por encima (sin pulsar). Otros elementos tienen atributos que son típicos de cada clase de elemento.

En líneas generales, la sintaxis para establecer los atributos en la etiqueta de apertura es:

<etiqueta atributo1="valor1" atributo2="valor2">

Los atributos se escriben separados por espacios en blanco, y cada uno en formato nombre=“valor”. Es común, aunque no obligatorio, entrecomillar los valores.

En el formato markdown las opciones de configuración son reducidas, pero la posibilidad de insertar etiquetas HTML, con sus atributos, nos ofrece más posibilidades.

Hojas de estilo

La presentación y aspecto de una página (colores, tipo de letra, etcétera) se configura con reglas de estilo. Estas reglas se escriben en un fichero aparte llamado “hoja de estilos”, con extensión .css

Cuando una página web se descarga acompañada de uno o varios archivos CSS, las reglas de estilo se aplican “en cascada”, solapándose a veces y estableciendo prioridades. De ahí que CSS signifique “cascade style sheets”.

La sintaxis CSS es complementaria de HTML. ¿Que aspecto tiene? Tomemos el siguiente archivo prueba.html:

<!DOCTYPE html>
    <head>
        <link rel="stylesheet" href="prueba.css">
    </head>
    <html>
        <body>

            <h1>Mi primer documento</h1>
            
            <p>Un texto <b>en negrita</b> 
            y este otro <i>en cursiva</i>.
            </p>

        </body>
    </html>

En la sección <head> de esta página web tenemos algo nuevo:

<link rel="stylesheet" href="prueba.css">

… lo que significa descargar el archivo adjunto prueba.css y usarlo como hoja de estilos.

Vamos a crear ese archivo prueba.css:

body {
  background-color: beige;
}

h1 {
  color: red;
  text-align: center;
}

p {
  font-family: verdana;
  font-size: 20px;
}

Como sucede con HTML, el lenguaje CSS permite insertar espacios en blanco extra para facilitar la lectura del fichero.

Este archivo contiene tres reglas de estilo. Cada regla está formada por:

• un selector, p, h1, body, etc, que indica a que elementos se va a aplicar

• un conjunto de propiedades de estilo, delimitadas cada una por un punto y coma, y todo ello entre llaves {}

• cada propiedad se escribe en formato:

  propiedad:valor ;
  

En el ejemplo, establecemos un color de fondo beige para todo el documento (body), el color de texto y alineamiento para los párrafos de cabecera de nivel 1, y la fuente y tamaño de letra para los párrafos en general.

Con estos dos archivos, prueba.html y prueba.css, al hacer doble clic sobre el primero, este se abrirá en la ventana del navegador web, enlazará con el segundo (de acuerdo con lo indicado en la etiqueta <link>) y veremos:

Si creamos nuestro sitio web en formato markdown y lo convertimos a HTML usando mdBook, no hace falta crear hojas de estilo. MdBook las genera automáticamente y las suma al resultado final. Pero nos permite añadir las nuestras propias. Lo veremos más adelante.

El atributo “style”

Las reglas de estilo de un archivo .css se aplican a todas las páginas que incluyan un enlace mediante la etiqueta <link> en la sección <head>. Hay otras dos formas de aplicar reglas de estilo:

• definir las reglas en la sección <head> del archivo HTML:

  <head>
      <style>
         
         body {background-color: beige;}
         
         h1 {color: red;}
         
         p {color: blue;}
     
      </style>
  </head>
  
  <body>
  
      Texto a mostrar
  
  </body>
  

  Estas reglas tienen prioridad sobre las declaradas en un archivo externo .css

• definir reglas concretas para un elemento en la etiqueta de apertura:

  <p style="regla1; regla2; regla3;" >
  

  Estas reglas tienen prioridad sobre las dos anteriores

Un ejemplo:

<p title="texto de ayuda"  style="color:red; text-align:center;" >

Pasar el ratón sobre este párrafo en color rojo.<br>
Se desplegará automáticamente un texto de ayuda, 
sin pulsar el ratón.

</p>

Lo que establece el párrafo como de color rojo y centrado, y muestra:

El formato del atributo style es:

<etiqueta style= " propiedad1:valor1 ; propiedad2:valor2 ; " > contenido </etiqueta>

Algunas propiedades de estilo comunes:

• color: black - determina el color del texto
• background-color: white - color del fondo
• font-family: Arial - fuente de letra
• font-style: italic - letra cursiva
• font-weight: bold - letra en negrita
• text-align: center - texto centrado
• font-size: 2em - tamaño doble de letra

CSS

---

La sintaxis CSS es un estándar complementario de HTML. Las capacidades del lenguaje CSS cubren todas las necesidades de una página web, y la descripción de estas reglas va más allá del propósito de este cuaderno. Existen numerosos tutoriales CSS y HTML en la red.

Clases

Dada una hoja de estilos, ¿como aplicar una regla a determinados elementos y a otros no? Una solución es declarar que un elemento pertenece a una clase (atributo class), y en la hoja de estilos, indicar las reglas aplicables a los elementos de esa clase.

Por ejemplo, supongamos que todos los elementos que queremos que vayan en color rojo los definimos como pertenecientes a la clase “rojo”:

<h1 class="rojo">Título del documento</h1>
<p class="rojo">Texto regular.</p> 

Y en la hoja de estilos definimos las propiedades de los elementos de esa clase, cuyo nombre se escribe con un punto de prefijo:

.rojo {
  color: red;
}

Si queremos que solo sea aplicable a los párrafos de cabecera, por ejemplo, en la hoja de estilos escribimos:

h1.rojo {
  color: red;
}

Y el resto de elementos de la clase “rojo” no se verán afectados.

Un elemento puede pertenecer a varias clases, que se especifican entre las comillas, y separadas por un espacio en blanco:

<p class="rojo importante">Texto regular</p> 

Identificadores

En una hoja de estilos podemos hacer referencia a un elemento concreto (por ejemplo, un párrafo) utilizando su nombre, precedido por un símbolo #:

#parrafo1 {
  text-align: center;
  color: red;
}

Debemos “bautizar” el elemento usando su atributo id:

<p id="parrafo1"> Texto centrado y en rojo </p>

Estos identificadores tienen otras utilidades. Por ejemplo, podemos crear un enlace a una sección del documento, asignando un ID al párrafo de título de la sección, y usándolo en la dirección de destino del enlace. Lo veremos en su momento.

Bloques

Podemos delimitar partes del documento entre etiquetas <div>

Texto regular

<div style="color:red;text-align:center">

    parte del documento en color rojo y centrado

</div>

resto del documento

También podemos señalar un fragmento dentro de un párrafo mediante la etiqueta <span>:

Este <span style="color:red">texto</span> se muestra en color rojo

lo que muestra:

¡Cuidado!

---

Si en un documento markdown insertamos un bloque entre etiquetas <div>, el contenido ha de ser html. La sintaxis markdown no tiene efecto en ese bloque.

Javascript

Además del formato de etiquetas HTML y las reglas de estilo CSS, la tercera “pata” del diseño web son los scripts, es decir, pequeños fragmentos de programación escritos en lenguaje JavaScript, que se descargan como parte del texto del archivo, o como ficheros aparte, con un nombre de archivo con el sufijo “.js”

Nota: El lenguaje JavaScript

---

JavaScript fue desarrollado originalmente por la empresa Netscape, quién desarrolló uno de los primeros navegadores web de la historia. El nombre se debió a los planes que tenía Netscape para que su navegador fuera compatible con la tecnología Java, de forma que ambos lenguajes de programación, Java y JavaScript fueran complementarios. Históricamente esto ha generado cierta confusión. De hecho, son lenguajes diferentes.

Como veremos más adelante, algunas de las funcionalidades incorporadas por mdBook se obtienen gracias a los archivos de script que se añaden automáticamente a los archivos web resultantes.

En este cuaderno no abordaremos el estudio del lenguaje JavaScript, porque daría pie a un libro aparte. Basta con saber que, si examinamos la carpeta donde se dejan los resultados producidos en el proceso de conversión, realizado por mdBook, los archivos con sufijo .js son pequeños programas que forman parte de nuestro libro y hacen cosas tales como mostrar el cuadro de búsquedas al pulsar en el icono o el cambio de esquema de colores al pulsar en el icono .

Espacio de trabajo

Ahora que ya sabemos que vamos a crear archivos de texto markdown y transformarlos para obtener páginas web, veamos las herramientas necesarias.

El editor de textos

El primer paso es descargar e instalar un editor de textos, del tipo plain text.

Inicialmente podemos usar el que viene de serie con nuestro sistema operativo. Más adelante buscaremos una solución más a la medida. Para crear archivos markdown, es costumbre utilizar editores especializados en esta tarea, que muestran dos paneles, uno de edición y otro de previsualización con el aspecto final del documento:

En la elección del editor existen cientos de alternativas. Una muy popular es Visual Studio Code, distribuido por Microsoft de forma gratuita, con versiones para diferentes sistemas operativos.

Visual Studio Code es un editor muy potente, con miles de posibilidades, que evoluciona rápidamente, y cuya descripción va más allá del propósito de este cuaderno. En todo caso, tenemos varias páginas web de interés:

• Página principal
• Documentación
• Editando archivos markdown

Si Visual Studio Code nos parece demasiado complejo, encontraremos otras opciones en la red. Basta con hacer una búsqueda del término “editores markdown”.

Terminal de comandos

Habitualmente ejecutamos programas pulsando sobre un icono del escritorio de nuestra computadora. Pero mdBook es un programa nacido en el seno de una comunidad de programadores, y entre ellos es más común hacer uso del Terminal de comandos proporcionado por el sistema operativo.

En Windows, se trata de un programa llamado cmd. Ver Wikipedia. En un ordenador Mac, encontraremos el programa Terminal en la carpeta Aplicaciones, apartado Utilidades.

Aunque los comandos difieren de un sistema a otro (Windows, Mac, Linux), los aquí descritos suelen ser comunes, quizás con ligeras diferencias.

Típicamente, al iniciar el Terminal se muestra un texto indicando la carpeta actual, es decir, la que se utiliza por defecto cuando en un comando no indicamos nada, seguida de un símbolo >, $, # u otro similar, denominado prompt:

C:\Users\nombreUsuario >

Este prompt nos invita a introducir un comando, que se ejecutará al pulsar Intro

Si no estamos familiarizados con los comandos de nuestro ordenador, en la red encontraremos numerosos tutoriales sobre el tema. En este cuaderno vamos a mencionar tres comandos bastante relevantes:

• para ejecutar un programa, se introduce su nombre. Por ejemplo, para iniciar el editor de texto bloc de notas en Windows, escribimos:

  > notepad
  

  Típicamente, los comandos pueden ir acompañados de “argumentos”. Por ejemplo, para iniciar el editor con un archivo abierto para su edición:

  > notepad miarchivo.txt
  

  Los argumentos se separan con espacios en blanco. Si un argumento contiene espacios, tendremos que entrecomillarlo:

  > notepad "mi archivo.txt"
  

• Las carpetas reciben el nombre de directorios. Para conocer cual es el directorio actual (el que se asume cuando no especificamos otro al ejecutar un comando) usar el comando cd en Windows o pwd en Mac/Linux

  > cd
  

  lo que muestra algo así como:

  C:\Users\nombreUsuario
  

• para establecer otro directorio como actual, usar el comando cd (cambiar de directorio) con el nombre de la carpeta en cuestión como argumento:

  > cd C:\directorio1\directorio2
  

  En las plataformas Mac/Linux se usa la barra / en lugar de la invertida \, que es típica de Windows:

  $ cd /directorio1/directorio2
  

Nota:

---

En los ejemplos de este cuaderno, los comandos se muestran precedidos del prompt $. No es algo que tengamos que teclear.

Nota:

---

Para redactar mis libros yo utilizo indistintamente computadoras Mac y Linux. Menciono el funcionamiento en Windows, pero los ejemplos de comandos están más orientados a lo que yo suelo usar ;)

Instalar mdBook

Descarga

mdBook es un programa que se puede descargar desde la página:

https://github.com/rust-lang/mdBook/releases

Tenemos opciones para:

• Windows x86_64
• Apple, en versión x86_64 y aarch64
• Linux, en versión x86_64 y aarch64

La descarga consiste en un archivo empaquetado en otro. Podemos extraer el contenido haciendo doble clic en el fichero descargado. Con esto obtenemos un ejecutable llamado mdbook que podemos mover a nuestra carpeta de proyectos.

En la carpeta de proyectos vamos a crear una subcarpeta llamada herramientas, donde colocaremos el archivo descargado. La organización será la siguiente:

proyectos/
  ├── libro1/
  ├── libro2/
  ├── libro3/
  │
  └── herramientas/
        └── mdbook

Verificar instalación

Abrimos el Terminal de comandos y nos situamos en la carpeta donde hemos dejado el programa, algo así como:

$ cd /Users/usuario/Documentos/Proyectos/herramientas

Ejecutamos mdBook preguntándole cual es la versión instalada:

$ mdbook --version

y deberíamos obtener un número de versión:

mdbook v0.5.2

¡Ojo! En sistemas tipo Linux o Mac, para ejecutar un programa, es necesario que su nombre vaya precedido por la carpeta donde se aloja. Tratándose de la carpeta actual, usamos el alias “.”

$ ./mdbook --version

Nota:

---

Como ya indiqué en la primera página, este cuaderno está orientado a usuarios que quieren desarrollar documentación en general, no a programadores Rust, para cuya documentación fue concebido mdBook originalmente.

Un programador de Rust haría la instalación descargando los programas originales (texto fuente) y compilándolos para obtener el programa final. Véase instrucciones en el manual de mdBook

Scripts de trabajo

El uso de comandos puede llegar a ser algo farragoso, por lo que es costumbre que, para realizar una tarea de forma repetitiva, creemos una lista de comandos y la pongamos en un archivo sobre el que haremos doble clic con el ratón para ejecutarlo. A este tipo de archivos de texto con comandos se les llama scripts.

Nuestro primer script

Vamos a crear una carpeta para nuestro primer proyecto. Seguidamente creamos un archivo llamado verificar_mdbook.sh.

Nota:

---

El sufijo .sh es típico de sistemas Linux o Mac, aunque se puede omitir. En Windows, suele ser .bat

El contenido del script puede ser algo así como:

clear
cd /Users/usuario/Documentos/Proyectos/miProyecto
../herramientas/mdbook --version
read

Veamos lo que significan estos cuatro comandos:

• clear. Al hacer doble clic sobre el script, este se ejecuta en una nueva ventana (dependiendo de los mecanismos de cada sistema operativo). El comando clear borra todos los mensajes iniciales.

  En Windows deberíamos escribir en su lugar:

  echo off
  cls
  

  lo que suprime “el eco” de comandos que se están ejecutando y borra el texto que haya en la ventana (clear screen).

• cd es un comando que nos situa en el directorio de trabajo especificado. En Windows sería algo así como:

  cd C:\carpeta1\carpeta2
  

• El comando mdbook invoca el programa. Va precedido por el directorio donde lo hemos instalado. Los dos puntos .. representan el directorio padre del actual, por lo que indicamos que busque el programa en ../herramientas

• read espera a que el usuario pulse una tecla antes de cerrar la ventana. En Windows el comando sería:

  pause
  

Identificar script como tal

En Windows, los scripts se identifican mediante el sufijo .bat

En Linux, la primera línea de texto ha der ser:

#!/usr/bin/env bash

cambiando bash por el nombre del programa shell (intérprete de comandos) que estemos usando en el Terminal (si no es bash). El texto del script queda así:

#!/usr/bin/env bash
clear
cd /Users/usuario/Documentos/Proyectos/miProyecto
../herramientas/mdbook --version
read

En Mac, para identificar un script como tal, pulsar sobre el mismo con el botón secundario del ratón y, en el menú emergente, seleccionar la opción “obtener información”. Configurar la opción “abrir con” y seleccionar el programa “Terminal”.

Permisos de ejecución

En Linux/Mac es necesario otorgar permisos de ejecución al script. Supongamos un fichero mi_script.sh. Abrimos el Terminal de comandos y ejecutamos:

$ cd /Users/usuario/Documentos/Proyectos/miProyecto
$ chmod +x mi_script.sh

El comando chmod sirve para cambiar los permisos. El argumento +x activa el permiso de ejecución del script que se indica.

Espacios en los argumentos

---

Ya hemos visto que, en los comandos, los argumentos se separan con espacios. Pero si el nombre de un programa, carpeta o fichero tiene espacios, podemos tener problemas:

cd mi carpeta En este caso, se buscará una carpeta llamada “mi”.

Hay dos formas de solucionar esto:

• evitar los espacios en los nombres de carpetas y ficheros (recomendado). Usar un carácter de subrayado en su lugar, o algo parecido:

  cd mi_carpeta
  cd miCarpeta
  

• entrecomillar los nombres de carpetas y ficheros:

  cd "mi carpeta"
  

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

… 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.

Servidor de cambios

Introducir contenidos con el editor y tener que esperar al proceso de conversión para ver los resultados finales puede ser algo frustrante. Pero existe un recurso alternativo, ejecutar mdBook en modo servidor. En el escritorio tendremos tres ventanas:

• la del editor de textos, donde estamos introduciendo los contenidos
• la ventana del Terminal de comandos, donde dejamos mdBook en ejecución permanente, atento a los cambios en los ficheros fuente
• la ventana del navegador web, donde mdBook va refrescando la futura página web a medida que guardamos los archivos.

Vamos a crear un script en la carpeta acciones para dejar a mdbook ejecutándose en modo servidor:

cd /Users/usuario/Documentos/Proyectos/miProyecto
../herramientas/mdbook serve --dest-dir temporal --open

Esto nos situa en la carpeta de proyecto (comando cd) y ejecuta mdbook con el comando serve. Le pasamos dos argumentos adicionales:

• temporal es el nombre de la carpeta de trabajo que vamos a crear con los contenidos provisionales ( dest-dir significa directorio de destino).

• el argumento --open abre la visualización de resultados en el navegador web, en una pestaña nueva.

Al ejecutarse este script, se abre la ventana de Terminal con los siguientes mensajes:

INFO Book building has started
INFO Running the html backend
INFO HTML book written to `/Users/usuario/Documentos/Proyectos/miProyecto/temporal`
INFO Serving on: http://localhost:3000
INFO Opening web browser
INFO Watching for changes...

… y seguidamente se abre el navegador web. Cada vez que modifiquemos un archivo fuente, mdBook actualizará el navegador. El proceso se detiene cerrando la ventana de Terminal (o seleccionándola y pulsando control+C)

El archivo de configuración de proyecto

Hemos iniciado el proyecto con el comando

mdbook init

y esto ha creado una estructura inicial de subcarpetas y archivos. En el directorio raíz hay un fichero especial llamado book.toml.

Sintaxis

El archivo de configuración contiene los parámetros del proyecto. Examinémoslo con el editor de textos:

[book]

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

Cada pareja clave = valor es un parámetro de configuración. Estos archivos siguen la sintaxis TOML. Véase Wikipedia.

En resumen, el contenido de un archivo de configuración puede tener:

• parejas clave=valor
• todas ellas agrupadas en secciones, encabezadas por un nombre de sección entre corchetes
• podemos insertar líneas en blanco para facilitar la lectura del fichero
• las líneas que empiezan por un carácter # se consideran como “comentarios” y serán ignoradas.

Los valores pueden ser:

• textos. Por ejemplo, el título del libro:

  title = "Mi primer libro"
  

• valores numéricos. No llevan comillas. Por ejemplo, el límite máximo de resultados en las búsquedas:

  limit-results = 20
  

• valores true/false (verdadero/falso). Por ejemplo, activar la creación automática de ficheros que no existen, pero se los menciona en el archivo SUMMARY.md. Esta anomalía se detecta en el proceso de generación del libro, tanto en modo build como serve.

  create-missing = true 
  

• listas de valores, entre corchetes y con los elementos separados por comas:

  authors = ["Pedro" , "Ana"]
  

Personalización

Vamos a cambiar algunos valores:

[book]
title = "Mi primer libro"
authors = ["Pedro" , "Ana"]
language = "es"
description = "Mi primer libro"
src = "src"

[build]
create-missing = false
build-dir = "book"  

[output.html]
default-theme = "rust"
preferred-dark-theme = "navy"

Hemos cambiado:

• el idioma, “es” en lugar de “en”. Esto no traduce elementos generados por mdBook, pero en el HTML final, en la sección <head> de cada página, se incluye esa información.

• el parámetro description también se añade como información añadida en la sección <head> del HTNL generado. La usan los buscadores web.

• he desactivado la creación automática de ficheros faltantes cuando están incluidos en SUMMARY.md. No me gusta que el programa actúe a mis espaldas e inadvertidamente cree ficheros por error.

• el tema por defecto. Si no hacemos nada suele ser light

• el tema a aplicar por defecto cuando el sistema operativo está configurado en dark.

• el directorio de salida para los resultados de la conversión a HTML. Aquí no es necesario, porque lo especificamos en el comando build o serve

• el directorio donde se encuentran los archivos fuente. No es necesario, porque es “src” por defecto. Pero podemos cambiarlo.

Estilos personalizados

Vamos a añadir algún toque personal a nuestro libro. Comenzamos por crear una subcarpeta theme:

miProyecto/
     ├── acciones/
     ├── book/
     ├── temporal/
     │     
     ├── theme/
     │
     ├── book.toml
     ├── .gitignore
     └── src
         ├── capitulo1.md
         ├── capitulo2.md
         ├── capitulo3.md
         └── SUMMARY.md 

En ese directorio ponemos un archivo estilos.css con un contenido que puede ser algo así como:

p { text-align: justify;}

h1 { font-size: 3em;}

h2 { border-bottom: 1px solid teal;}

h3 { font-style: italic; }

.menu-title { color: chocolate; }
    
.conmarco {box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 
                       0 6px 20px 0 rgba(0, 0, 0, 0.19);
           padding: 10px;
          }

Veamos lo que significa esto:

• me gusta que los párrafos regulares <p> muestren el texto justificado, ajustado a los margenes izquierdo y derecho a la vez.

• he aumentado el tamaño de letra de los títulos de nivel 1 a tres veces el texto regular

• he añadido una línea de borde inferior a los títulos de nivel 2 (secciones), con un pixel de grosor (un punto en pantalla) y color azulado (teal)

• he puesto en cursiva los títulos de nivel 3

• he puesto el título superior de cada página en un color rojizo suave (chocolate)

He creado una clase “conmarco” para aplicar a bloques de la página. Se usa así:

<div class=conmarco>

<p>Texto a mostrar resaltado</p>

<p>Debe escribirse directamente en HTML</p>

</div>

Lo que muestra:

No olvidar que todo lo delimitado entre etiquetas <div> debe escribirse en formato HTML. La sintaxis markdown no tiene efecto en estos bloques.

Para que nuestros archivos CSS tengan efecto, hemos de ponerlos en el archivo de configuración book.toml:

[output.html]
additional-css = ["theme/estilos1.css" , "theme/estilos2.css"]

Nótese que es una lista de ficheros. Si solo es uno, no olvidar los corchetes:

[output.html]
additional-css = ["theme/estilos.css"]

Plantillas

Para generar páginas HTML, mdBook usa unas plantillas. Podemos obtener una copia de la siguiente forma:

• Nos situamos en el directorio raíz de todos nuestros proyectos y creamos una subcarpeta de pruebas. Nos situamos en ella:

  $ cd /Users/usuario/Documentos/Proyectos/prueba
  

• Creamos un proyecto “de pega”

  $ ../herramientas/mdbook init --theme
  

Se crea un nuevo embrión de libro. El argumento --theme fuerza a que mdBook cree una subcarpeta theme con los estilos, javascripts, iconos y demás materiales usados por defecto, que podemos modificar. En resumen, si mdBook encuentra aquí cualquier objeto, modificado o no, lo usará con prioridad sobre los suyos propios.

Podemos copiar estos ficheros, desde esta carpeta de pruebas a las carpetas de nuestros proyectos.

La plantilla de página web es index.hbs. La copiamos a nuestro proyecto de libro, dejándola en el directorio theme:

miProyecto/
     ├── acciones/
     ├── book/
     ├── temporal/
     │     
     ├── theme/
     │   ├── misestilos.css
     │   └── index.hbs
     │
     ├── book.toml
     ├── .gitignore
     │
     └── src
         ├── capitulo1.md
         ├── capitulo2.md
         ├── capitulo3.md
         └── SUMMARY.md 

Si examinamos este archivo index.hbs con un editor de textos, veremos una sintaxis que se corresponde con el lenguaje de plantillas handlebars. Por ejemplo, el texto de la plantilla comienza con:

<!DOCTYPE HTML>
<html lang="{{ language }}" class="{{ default_theme }} sidebar-visible" dir="{{ text_direction }}">
    <head>
    ...

… lo que, al generar los ficheros HTML, se convierte en:

<!DOCTYPE HTML>
<html lang="es" class="rust sidebar-visible" dir="ltr">
    <head>
    ... 

De forma que:

• {{ language }} se sustituye por el idioma que hemos establecido en el archivo book.toml

• {{ default_theme }} se sustituye por el nombre del tema por defecto

• {{ text_direction }} se sustituye por la dirección del texto (ltr= left to right)

En resumen, mdBook toma la plantilla, hace las sustituciones necesarias, y el resultado es el HTML definitivo. Esto lo hace para cada página del libro.

Traduciendo la ventana de ayuda

Ya hemos visto que pulsando en la tecla ? se muestra un recuadro emergente con un resumen de teclas de atajo:

Vamos a traducirlo. En el archivo index.hbs buscamos algún fragmento de este texto. Lo que encontramos es algo así como:

<div id="mdbook-help-popup">
    <h2 class="mdbook-help-title">Keyboard shortcuts</h2>
    
    <div>
        <p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
        {{#if search_enabled}}
        <p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
        {{/if}}
        <p>Press <kbd>?</kbd> to show this help</p>
        <p>Press <kbd>Esc</kbd> to hide this help</p>
    </div>

</div>

Lo modificamos:

<div id="mdbook-help-popup">
    <h2 class="mdbook-help-title">Teclas de atajo</h2>
    <div>
        <p>Pulse <kbd>←</kbd> o <kbd>→</kbd> para navegar entre capítulos</p>
        {{#if search_enabled}}
        <p>Pulse <kbd>S</kbd> o <kbd>/</kbd> para hacer búsquedas</p>
        {{/if}}
        <p>Pulse <kbd>?</kbd> para mostrar esta ayuda</p>
        <p>Pulse <kbd>Esc</kbd> para ocultar esta ayuda</p>
    </div>
</div>

Y al servir páginas y pulsar en la tecla ?, veremos la ventana emergente traducida.

Por este procedimiento también podemos traducir las etiquetas que se muestran al pasar el ratón sobre los iconos de la barra superior, o sobre los botones de página siguiente/anterior.

La barra de navegación

El archivo SUMMARY.md es usado por mdBook para generar la barra lateral, establecer la jerarquía de capítulos y subcapítulos, y crear enlaces a la ubicación de los archivos. Sin este archivo SUMMARY.md, no hay libro.

El formato es markdown, y debe llamarse SUMMARY.md. Su formato es muy estricto y debe seguir las normas que se detallan a continuación para poder ser analizado por mdBook.

Formato

El contenido del archivo consiste en una lista de enlaces en el siguiente formato:

- [Texto 1](ruta/archivo1.md)
- [Texto 2](ruta/archivo2.md)
- [Texto 3](ruta/archivo3.md)

Cada entrada tiene la forma:

[Texto a mostrar](archivo)

Se asume que los archivos están en la carpeta src. Si usamos subcarpetas, hay que especificarlas:

[Texto a mostrar](ruta/archivo)

Podemos crear una estructura de capítulos y subcapítulos. Introducir las sangrías adecuadas::

- [Texto 1](ruta/archivo1.md)
  - [Texto 2](ruta/archivo2.md)
  - [Texto 3](ruta/archivo3.md)
- [Texto 4](ruta/archivo4.md)
  - [Texto 5](ruta/archivo5.md)
  - [Texto 6](ruta/archivo6.md)

Esto resulta útil para:

• agrupar los capítulos visualmente
• numerarlos de acuerdo a la jerarquía

Archivos no incluidos

En principio, en el archivo SUMMARY.md deberíamos incluir todos los ficheros markdown dentro de la carpeta /src o sus subcarpetas. Se puede cambiar la carpeta src por defecto configurándolo en el archivo book.toml:

[book]
src = "documentos" 

Cuando un fichero markdown no se incluye en la lista de SUMMARY.md, la página se crea en formato HTML, pero no será accesible desde el panel lateral. En alguna parte de la documentación tendremos que poner a mano los correspondientes enlaces.

Evitar numeración automática

La numeración de capítulos es automática, aunque solo se visualiza en la barra lateral. No se modifican los párrafos de cabecera en el contenido de cada página.

Se puede desactivar si quitamos los guiones de prefijo (o asteriscos):

[Texto 1](ruta/archivo1.md)
[Texto 2](ruta/archivo2.md)
[Texto 3](ruta/archivo3.md)

en lugar de:

- [Texto 1](ruta/archivo1.md)
- [Texto 2](ruta/archivo2.md)
- [Texto 3](ruta/archivo3.md)

Hay otra forma de suprimir toda numeración automática. Consiste en añadir al archivo de configuración book.toml lo siguiente:

[output.html]
no-section-label = false

Títulos

En el fichero SUMMARY.md hay una primera línea que es opcional y será ignorada.

# Summary

Podemos dejarla y añadir nuevas líneas de título antes de cada bloque de capítulo. Estas sí se visualizarán:

# Sumario

# Apartado 1
- [Texto 1](ruta/archivo1.md)
- [Texto 2](ruta/archivo2.md)
- [Texto 3](ruta/archivo3.md)

# Apartado 2
- [Texto 4](ruta/archivo4.md)
- [Texto 5](ruta/archivo5.md)
- [Texto 6](ruta/archivo6.md)

Los títulos no pueden sangrarse.

Capítulo de prefijo/sufijo

En principio, no es posible mezclar capítulos numerados (con un guión o asterisco) con capítulos no numerados. Pero si los numeramos, es posible poner un capítulo inicial o y otro final sin numerar:

[Introducción](ruta/archivo_prefijo.md)
- [Capítulo 1](ruta/archivo1.md)
- [Capítulo 2](ruta/archivo2.md)
- [Capítulo 3](ruta/archivo3.md)
[Conclusión](ruta/archivo_sufijo.md)

Borradores

Los draft chapters son capítulos sin un fichero ni contenido (paréntesis vacíos). Sirven para señalizar futuros capítulos pendientes de escribir. También se usan para organizar la estructura del libro sin señalar un archivo y evitar que se genere automáticamente.

Los draft chapters se convertirán a HTML como enlaces desactivados.

- [Capítulo]()

Separadores

Para insertar líneas separadoras, escribir una línea de al menos tres guiones:

# Título

[Introducción](ruta/markdown.md)

---

- [Capítulo 1](ruta/markdown2.md)
- [Capítulo 2](ruta/markdown2.md)

Plegado

Por defecto, cuando pulsamos sobre un capítulo se despliega un índice de contenido formado por las cabeceras de secciones.

Si tenemos una estructura de capítulos/subcapítulos, estos últimos se mantienen a la vista. Podemos forzar un plegado añadiendo lo siguiente al archivo de configuración book.toml:

[output.html.fold]
enable = true    
level = 0        

Cuanto mayor sea el nivel, más niveles se mostrarán desplegados. Por defecto es cero, y solo se muestran los capítulos principales.

Página 404

Los errores suceden. Y hay veces en las que, al pulsar sobre un enlace, no se encuentra la página enlazada. Quizás haya un usuario intentando leer el libro mientras estamos en mitad de la tarea de actualización del sitio web.

En estos casos se suele mostrar una página de error:

Document not found (404)

This URL is invalid, sorry. Please use the navigation bar or search to continue.

Acudamos al directorio donde hemos dejado el resultado del proceso de generación del libro. Hay una página 404.html estándar que es la que se muestra en estas situaciones.

Podemos crear una página personalizada, algo así como:

Tenemos un problema …..

Página no encontrada

Creamos un archivo markdown con esta página, por ejemplo, src/problemas.md. En el fichero de configuración la señalamos como página de errores:

[output.html]
input-404 = "problemas.md"

… considerando que el fichero está en la carpeta /src. En caso contrario, debe escribirse precedido por la ruta:

[output.html]
input-404 = "docs/problemas.md"

Imprimir libro

Por defecto, mdBook incluye un icono en la barra de cabecera. Pulsando en el mismo, podemos imprimir el libro completo enviándolo a la impresora o a un archivo PDF (dependiendo del sistema operativo del usuario).

Podemos desactivar esta función mediante:

[output.html.print]
enable = false

Podemos insertar saltos de página tras cada capítulo (activado por defecto) mediante:

[output.html.print]
enable = true
page-break = true

La función de imprimir libro se construye incluyendo en el libro generado una página especial print.hmtl que recoge el contenido de todas las páginas. Por este motivo, no debemos incluir en nuestro libro un capítulo con ese nombre, ya que está reservado por mdBook.

Configurar búsquedas

En cada página del libro se incluye un icono de búsqueda en la barra superior. Pulsando en él, se abre una caja para introducir textos de búsqueda.

A medida que tecleamos el texto a buscar, se va mostrando una lista de resultados.

Podemos pulsar con el ratón en alguna de las entradas de la lista para ir a esa página, o bien pulsar la tecla Esc para abandonar. También podemos usar las teclas de flecha ↑ ↓ para desplazarnos por la lista y pulsar enter para seleccionar el elemento resaltado.

Podemos desactivar esta función desde el archivo de configuración book.toml

[output.html.search]
enable = true       

La tabla [output.html.search] proporciona opciones para configurar el proceso:

[output.html.search]

enable = true            # activa las búsquedas
limit-results = 30       # máximo número de resultados
teaser-word-count = 30   # número de palabras usadas en los resultados
use-boolean-and = true   # deben coincidir todas las palabras
boost-title = 2          # importancia de coincidencias en títulos
boost-hierarchy = 1      # importancia de coincidencias en nombres de páginas
boost-paragraph = 1      # importancia de coincidencias en texto
expand = true            # aceptar coincidencia con términos más largos
heading-split-level = 3  # nivel de cabecera al que enlazar
copy-js = true           # incluir Javascript de búsquedas

las opciones son:

• enable: Activar las búsquedas. Por defecto es true.

• limit-results: Máximo número de resultados. Por defecto es 30.

• teaser-word-count: Número de palabras usadas en cada entrada de la lista de resultados. Por defecto es 30.

• use-boolean-and: Si es true, todas las palabras de búsqueda deben encontrarse en los resultados. Por defecto es false.

• boost-title: Factor de importancia de cada resultado cuando el texto aparece en una cabecera. Por defecto es 2.

• boost-hierarchy: Factor de importancia de cada resultado cuando el texto aparece en la jerarquía de títulos. Por defecto es 1.

• boost-paragraph: Factor de importancia de cada resultado cuando el texto aparece en el texto. Por defecto es 1.

• expand: True si las coincidencias con palabras más largas deben considerarse válidas. Por defecto es true.

• heading-split-level: Pulsando en un resultado, se irá al párrafo de título de sección correspondiente. Por defecto se va hasta el nivel 3 (cabeceras que empiezan con ###) si existe.

• copy-js: Incluye los archivos JavaScript estándar de mdBook. Por defecto es true.

La tabla [output.html.search.chapter] permite configurar incluir o excluir capítulos o directorios por separado. Cada entrada de la tabla es una ruta a un archivo o directorio, seguida de una subtabla de configuraciones a aplicar a esa ruta. Se pueden solapar, tomando precedencia las rutas más específicas.

[output.html.search.chapter]

# Desactivar búsquedas para todos los capítulos en el directorio `carpeta1` 
"carpeta1" = { enable = false }

# Activar búsquedas para el capítulo `glosario`
"carpeta1/glosario.md" = { enable = true }

La opción enable activa o desactiva las búsquedas para los capítulos indicados. Por defecto es true. Esto no sobreescribe la configuración output.html.search.enable, que ha de ser true para cualquier búsqueda que deba estar activada.

Téngase cuidado al deshabilitar la indexación para determinados capítulos porque eso puede llevar a la confusión del usuario cuando busca términos y esperan que se encuentren. Esto solo debe usarse en circunstancias excepcionales en las que mantener el capítulo en el índice causará problemas con la calidad de los resultados de búsqueda.

Acerca de Markdown

Markdown es un formato sencillo y fácil de escribir, ideado en 2004 por John Gruber. Se trata de un proyecto que ha evolucionado muy poco desde su creación, lo que ha dado lugar a que surjan diferentes versiones mejoradas.

El proceso de conversión de mdBook se ajusta a las reglas de sintaxis de una versión denominada CommonMark, con algunos añadidos. El módulo de generación de HTML es un programa desarrollado en lenguaje Rust, tomando como base un proyecto denominado pulldown-cmark.

En este cuaderno no se pretende hace un repaso exhaustivo de Markdown, aunque podemos acudir al documento técnico de especificaciones de CommonMark, quien también proporciona un tutorial que podemos examinar, y un editor para hacer pruebas.

Otro recurso es la página Markdown Guide.

Parrafos

En cada documento, todas las líneas de texto se unirán para formar una sola. Es decir, lo siguiente:

texto 1
texto 2
texto 3
texto 4

Se mostrará en el navegador como:

texto 1 texto 2 texto 3 texto 4

Los saltos de línea se suprimirán en la visualización de la página.

Para separar párrafos insertando un espaciado entre ellos, en la sintaxis Markdown debemos dejar al menos una línea en blanco entre párrafo y párrafo. Múltiples líneas en blanco consecutivas serán ignoradas:

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.

Los párrafos deben alinearse al borde izquierdo, ya que la sangría se usa para propósitos especiales en los archivos markdown. Por el contrario, en los ficheros HTML es puramente decorativa.

Al convertir de markdown a HTML, cada párrafo se delimitará entre etiquetas <p>:

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod 
tempor incididunt ut labore et dolore magna aliqua. </p>

Saltos de línea

Para forzar un salto de línea dentro de un párrafo en un texto markdown, añadir al final de la línea dos o más espacios. Es decir lo siguiente:

texto1  
texto2  

Respetará las líneas. Pero este mecanismo resulta controvertido, ya que, en un editor, los espacios añadidos al final de la línea pasan inadvertidos, lo que dará lugar a errores. Es preferible insertar una etiqueta HTML <br> (line break) allá donde queramos un salto:

texto1<br>
texto2<br>

Lo que resulta en:

texto1
texto2

También obtenemos el mismo resultado con:

texto1<br>texto2<br>

Dibujar una línea entre párrafos

Podemos dibujar una línea entre dos párrafos insertando una etiqueta <hr> (horizontal rule):

Nota:
<hr>

Observaciones a tener en cuenta

Lo que muestra:

Nota:

---

Observaciones a tener en cuenta

Una etiqueta <hr> dentro de un párrafo lo separa en dos párrafos:

Nota:<hr>Observaciones a tener en cuenta

En formato markdown podemos obtener una línea horizontal insertando tres guiones. Lo anterior se puede lograr mediante:

Nota:

---

Observaciones a tener en cuenta

Podemos usar guiones, asteriscos o caracteres de subrayado, y pueden ser más de tres caracteres:

***

-------

_________________

Cabeceras

Los párrafos de cabecera se muestran con un tipo de letra resaltado. Se usan como título de capítulo, sección, subsección, etcétera.

En formato HTML podemos tener hasta seis niveles de resaltado:

<h1>Título nivel 1</h1>

<h2>Título nivel 2</h2>

<h3>Título nivel 3</h3>

<h4>Título nivel 4</h4>

<h5>Título nivel 5</h5>

<h6>Título nivel 6</h6>

<p> Texto regular </p>

Lo que muestra:

Título nivel 1

Título nivel 2

Título nivel 3

Título nivel 4

Título nivel 5

Título nivel 6

Texto regular

El tamaño de letra, presentación, etcétera, se puede ajustar con hojas de estilo CSS. Lo que vemos en este ejemplo se muestra de acuerdo a los estilos aplicados a este cuaderno:

h1 { font-size: 3em;}

h2 { border-bottom: 1px solid teal;}

h3 { font-style: italic; }

En formato markdown, las cabeceras se señalan como párrafos de una única línea de texto, precedidos por tantos símbolos # como nivel deseemos:

# Título nivel 1

## Título nivel 2

### Título nivel 3

####Título nivel 4

##### Título nivel 5

###### Título nivel 6

Texto regular

A este formato se le denomina “atx”. Entre los símbolos # y el texto se suele dejar algún espacio. Esto depende de cada versión de markdown, pero se recomienda respetar por compatibilidad. También es costumbre dejar una línea en blanco antes y después de cada cabecera.

Podemos añadir cualquier número de caracteres # a la derecha del título, que serán ignorados:

# Título nivel1 ###########

## Título nivel2 ##########

Texto regular

Estilo “setext”

Como alternativa al formato “atx”, podemos usar el estilo “setext”, limitado a dos niveles:

Título nivel 1
==============

Título nivel 2
--------------

Texto regular.

En estilo setext las cabeceras de nivel 1 se subrayan con símbolos =, y las de nivel 2, con símbolos -. El número de caracteres que forman el subrayado no tiene por que coincidir con el tamaño del texto, y este puede ser multilínea:

Título 
nivel 1
==============

A tener en cuenta

Podría ser tentador definir un párrafo como cabecera solo para resaltarlo, pero esta es una mala práctica.

Las cabeceras no se limitan a aplicar un tipo de letra especial. Proporcionan una estructura al documento, y los motores de búsqueda las utilizan para indexar los contenidos. Además, mdBook las utiliza para generar el índice de la barra lateral.

Las cabeceras <h1> deberían utilizarse para el título del documento, seguidas de las <h2> y así sucesivamente. No debemos usar estas etiquetas solo para resaltar texto en negrita o mostrarlo más grande. Para ese propósito tenemos las hojas de estilo.

Énfasis

Al margen de las hojas de estilo, en la sintaxis HTML hay algunos recursos básicos que nos permiten resaltar texto:

<p>Esta <i>palabra</i> está resaltada en cursiva.</p>

Lo que muestra “palabra” en cursiva:

Las etiquetas HTML de formato son:

Los elementos <b> y <strong> se suelen mostrar en negrita, pero el propósito es diferente. Con la etiqueta <strong> estamos resaltando la importancia del texto:

<strong>Esto es importante</strong>

Lo mismo sucede con las etiquetas <i> y <em>, que se muestran en letra cursiva (itálica), pero en el caso de <em>, lo que se desea es enfatizar el texto.

<em>Texto enfatizado</em>

El elemento <del> indica texto eliminado del documento. Generalmente se muestra tachado con una raya. El elemento <ins> define texto añadido, que se suele mostrar subrayado:

<del>Texto suprimido</del><ins>Texto añadido</ins>

Muestra:

Los elementos <sub> y <sup> se usan para mostrar subíndices y superíndices. Por ejemplo:

Fórmula del agua: <em>H<sup>2</sup>O</em>

Muestra:

En formato markdown tenemos algunas marcas que podemos usar en lugar de las etiquetas:

Lo que se escribe entre asteriscos *se muestra en cursiva*

Lo que se escribe entre doble asterisco **se muestra en negrita**

~Esto se muestra tachado~

Muestra:

Lo que se escribe entre asteriscos se muestra en cursiva

Lo que se escribe entre doble asterisco se muestra en negrita

Esto se muestra tachado

Nota: el marcador ~ es un añadido de mdBook. No forma parte de las especificaciones oficiales del formato markdown estándar.

En lugar de asteriscos, podemos usar el carácter de subrayado:

Lo que se escribe entre asteriscos _se muestra en cursiva_

Lo que se escribe entre doble asterisco __se muestra en negrita__

¿Que pasa si queremos que un asterisco forma parte del texto regular? Si cualquier carácter va precedido de una barra invertida \, esta no se mostrará, y el carácter será considerado como texto a mostrar:

\*Esto no va en cursiva\*

Muestra:

*Esto no va en cursiva*

Para enfatizar el texto con negrita y cursiva al mismo tiempo, poner tres asteriscos o subrayados antes y después del texto, o combinar ambos marcadores:

Este texto es **_importante_**.

Párrafos de cita

Un párrafo de cita es aquel que se destaca en un formato especial:

Hay dos cosas que son infinitas: el universo y la estupidez humana; de la primera no estoy muy seguro (Albert Einstein)

En HTML, esto se obtiene sustituyendo las etiquetas <p> por <blockquote>>

<blockquote>
<i>Hay dos cosas que son infinitas: el universo y la estupidez humana; 
de la primera no estoy muy seguro</i> (Albert Einstein)
</blockquote>

Una vez más, el formato de resaltado depende de los estilos aplicados. Nótese que podemos poner ub bloque dentro de otro, en este ejemplo, un bloque <i> dentro de otro <blockquote>.

En formato markdown, los párrafos de cita se marcan anteponiendo un carácter > en cada línea:

> *Hay dos cosas que son infinitas: 
> el universo y la estupidez humana; 
> de la primera no estoy muy seguro*
> (Albert Einstein)

Véase que se admiten otras marcas dentro del párrafo, como es el caso de los asteriscos en este ejemplo.

Como sucede con los párrafos regulares, las líneas serán unidas en una sola. Podemos crear citas de varios párrafos:

> *Hay dos cosas que son infinitas: 
> el universo y la estupidez humana; 
> de la primera no estoy muy seguro*
>
> (Albert Einstein)

Podemos poner cualquier elemento markdown dentro de una cita, incluso crear nuevas citas internamente:

> *Hay dos cosas que son infinitas: 
> el universo y la estupidez humana; 
> de la primera no estoy muy seguro*
>
>> (Albert Einstein)

Lo que muestra:

Hay dos cosas que son infinitas: el universo y la estupidez humana; de la primera no estoy muy seguro

(Albert Einstein)

Listas

Una lista es una sucesión de elementos precedidos por una viñeta:

• Té
• Café
• Leche

Los elementos pueden ser párrafos completos:

• 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.

Un elemento puede ser multipárrafo:

• 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.

Las listas pueden ser de dos tipos, con viñetas o numeradas:

1. Té
2. Café
3. Leche

Podemos poner una lista dentro de otra (listas anidadas)

1. Té

2. Café

   • Solo
   • Cortado
   • Con crema

3. Leche

Formato html

Las listas numeradas (ordered lists) se delimitan entre etiquetas <ol>, Cada elemento, entre etiquetas <li>:

<ol>
  <li>Té    </li>
  <li>Café  </li>
  <li>Leche </li>
</ol>

Nótese que la numeración no forma parte del texto del archivo HTML. Los navegadores web la generan automáticamente.

Las listas con viñetas (unordered lists) se delimitan entre etiquetas <ul>:

<ul>
  <li>Té    </li>
  <li>Café  </li>
  <li>Leche </li>
</ul>

Ejemplo de una lista dentro de otra:

<ol>
  <li>Té    </li>
  <li>Café  
      <ul>
          <li>Solo      </li>
          <li>Cortado   </li>
          <li>Con crema </li>
      </ul>
  </li>
  <li>Leche </li>
</ol>

Formato markdown

Las listas no ordenadas se indican usando un símbolo -, + o * como viñeta, y delimitando todo el conjunto entre líneas en blanco, como haríamos con cualquier otro bloque:

Bebidas:

- Té
- Café

  * Solo
  * Cortado
  * Con crema

- Leche

Podemos usar la misma viñeta para diferentes listas, pero no podemos mezclar viñetas dentro de una lista. No podemos escribir:

- Té
* Café
- Leche

Podemos separar los elementos con líneas en blanco:

- Té

- Café

- Leche

Las listas ordenadas se especifican mediante

1. Té
2. Café
3. Leche

La numeración usada es irrelevante, ya que, como hemos visto, no se guarda en la sintaxis HTML. Lo siguiente es válido:

1. Té
1. Café
1. Leche

Podemos anidar diferentes estilos de lista:

- Té
- Café
  1. Solo
  2. Cortado
  3. Con crema
- Leche

Se consideran que un elemento forma parte de la lista anidada si las viñetas (o números) están al mismo nivel de sangría que el resto de elementos.

Los elementos multipárrafo deben respetar el mismo sangrado para todo el elemento:

- Té

- Café
  
  No conviene abusar.
  
- Leche

Texto de programas

Imaginemos que estamos creando un libro sobre el lenguaje de programación Python, y en el archivo markdown escribimos:

Ejemplo de programa Python:

x = 7
y = 3
z = x*y*2
print(z)

lo que se verá así:

Ejemplo de programa Python:

x = 7 y = 3 z = xy2 print(z)

Tenemos un problema. El conjunto de instrucciones del programa de ejemplo se deshace para formar una línea única, y los asteriscos, que representan una multiplicación, se interpretan como letra en cursiva.

Queremos que el texto del programa no sea interpretado, y se muestre tal cual, respetando todos los caracteres, formato y saltos de línea. Lo logramos sangrándolo cuatro espacios:

Ejemplo de programa Python:

    x = 7
    y = 3
    z = x*y*2
    print(z)

Lo que muestra:

Ejemplo de programa Python:

x = 7
y = 3
z = x*y*2
print(z)

Este tipo de bloques sangrados forman lo que se conoce como bloques preformateados. Las marcas HTML y markdown no se interpretan, y se muestran tal cual. El tipo de letra usado suele ser monoespaciada. Los efectos de color suelen establecerse con hojas de estilo css.

Copiar bloque

Los bloques preformateados tienen una característica especial. MdBook hace que, al pasar el ratón por el texto del bloque, en la esquina del recuadro se muestre un icono para copiar el contenido al portapapeles.

Probemos a pasar el ratón sobre lo siguiente:

texto a copiar

Fragmentos de párrafos

Existe un caso especial de texto preformateado, el que se limita a un fragmento de párrafo. Por ejemplo:

Usar *texto entre asteriscos* para mostrar en cursiva

Aquí vemos que respetamos los asteriscos como texto regular y mostramos el fragmento con un tipo de letra especial. esto se logra delimitándolo entre acentos invertidos (backticks):

Usar `*texto entre asteriscos*` para mostrar en cursiva

En el resultado final, se suprime la visualización de los backtics, se respeta el contenido del fragmento, y se muestra con una fuente de letra monosespaciada y resaltada:

¿Que pasa si el contenido del fragmento tiene a su vez caracteres ` backtick que hay que respetar? Usar un doble backtick como delimitador:

``Esto contiene caracteres ` backtick``

¿Como hacer que los baskticks se consideren como texto regular? Precederlos por una barra invertida, que será suprimida del resultado final:

Este párrafo contiene caracteres \` backtick

Lo que muestra el párrafo como texto regular:

Este párrafo contiene caracteres ` backtick

Enlaces

Una de las características más importantes de toda página web es la posibilidad de insertar enlaces en el texto. Por ejemplo, un enlace a la Wikipedia.

Todo enlace está formado por dos partes, el texto a mostrar y la dirección URL enlazada. El ejemplo anterior se escribe de la siguiente forma en formato HTML:

... un <a href="https://es.wikipedia.org">enlace a la Wikipedia</a>.

De forma que, el texto a mostrar se delimita entre etiquetas <a>, y la URL enlazada mediante el atributo href en la etiqueta de apertura.

El formato markdown es más simple:

... un [enlace a la Wikipedia](https://es.wikipedia.org).

El texto del enlace se escribe entre corchetes, seguido de la URL entre paréntesis (y sin espacios entre ambos elementos).

Esta forma de escritura tiene una alternativa que permite mantener el texto más limpio. Consiste en sacar las URL fuera de todo párrafo:

Por ejemplo, un [enlace a la Wikipedia].

[enlace a la Wikipedia]: https://es.wikipedia.org
[otro enlace]: https://mipagina.org

Podemos mezclar ambos estilos, y las URLs se pueden poner en cualquier parte del documento. Hay quien prefiere agruparlas al final del archivo. Yo prefiero ponerlas tras cada párrafo donde se utilizan. Nótese que, siguiendo este segundo estilo, las URLs no se escriben entre paréntesis, y el texto del enlace va seguido de dos puntos tras el corchete de cierre.

Enlaces a capítulos

Para crear un enlace a un capítulo del libro, poner el nombre del fichero en lugar de la URL

Véase [capítulo 2](capitulo2.md).

considerando que podemos tener una estructura de carpetas dentro del directorio src:

Véase [capítulo 2](docs/capitulo2.md).

Podemos enlazar directamente a un párrafo de cabecera añadiendo un carácter # y el identificador del párrafo.

Véase [capítulo 2](docs/capitulo2.md#enlaces-a-capítulos).

El identificador se forma transformando el texto de la cabecera a minúsculas y sustituyendo los espacios por guiones.

Mostrar URLS como texto del enlace

Podemos insertar una URL en el texto del documento, delimitándola entre < >. Se usará como texto del enlace y destino, al mismo tiempo.

Para ir a la Wikipedia pulse en <https://es.wikipedia.org>.

Lo que muestra:

Para ir a la Wikipedia pulse en https://es.wikipedia.org.

Espacios en blanco

Es una mala práctica que una URL tenga espacios en blanco, pero a veces pasa:

[link](https://www.ejemplo.com/mi pagina)

Todos los caracteres de un archivo tienen un código, y el del espacio en blanco es %20. Podemos usarlo en este caso:

[link](https://www.ejemplo.com/mi%20pagina)

Imágenes

Insertar una imagen

Los archivos de imagenes son ficheros binarios que no pueden formar parte de un archivo plain text, ni en el caso de los ficheros markdown, ni en los HTML. Cuando accedemos al sitio web, las imágenes se descargan en paralelo junto al archivo HTML y nuestro navegador hará una composición “al vuelo” para mostrar la página.

El archivo HTML ha de llevar en su texto una etiqueta <img>, para indicar al navegador el punto del documento donde hay que visualizar la imagen.

Veamos un ejemplo de archivo HTML. Vamos a insertar directamente una etiqueta <img> entre párrafo y párrafo:

<p>Emoji smiley:</p>

<p><img src="../img/0409imagenes_Smiley.png" 
             alt="Smiley" 
             width="150" 
             height="150">
</p>

<p>
  Imagen con licencia de 
  <a href="https://pixabay.com/es/illustrations/smiley-emoticon-emoji-cómic-4832495/">
  Pixabay
  </a>
</p>

Lo que muestra:

Las imágenes consisten en una única etiqueta HTML <img>, sin etiqueta de cierre. Entre otros, podemos poner los siguientes atributos:

• src="nombre_archivo" - Indica el archivo a descargar y mostrar. En nuestro ejemplo, indicamos un fichero en la carpeta img/ que cuelga de la carpeta “padre” donde tenemos los documentos, es decir, en src/img

• alt="texto" - Texto alternativo cuando no se puede mostrar la imagen

• width y height permiten establecer el tamaño de visualización

• title="texto"- Recuadro a mostrar cuando pasamos el ratón sobre la imagen.

Como alternativa al uso de etiquetas HTML, la sintaxis Markdown cuenta con el siguiente formato:

![texto alternativo](../img/Smiley.png)

Véase que el formato es el mismo que para los enlaces, añadiendo un prefijo !.

Markdown no cuenta inicialmente con otras opciones, aunque podemos añadir el atributo title tras el nombre del archivo:

![texto alternativo](/carpeta/imagen.jpg "Título")

Si necesitamos especificar tamaño u otros atributos, tendremos que usar directamente una etiqueta <img> insertada en el texto markdown.

Posicionamiento de las imágenes

En el ejemplo anterior, poníamos la imagen entre párrafo y párrafo, pero podemos insertarla dentro del texto de uno de los párrafos, lo que la muestra entre carácter y carácter, alineada con el borde inferior del párrafo:

Emoji smiley
<img src="../img/Smiley.png" width="150" height="150"> 
con licencia de 
[Pixabay](https://pixabay.com/es/illustrations/smiley-emoticon-emoji-cómic-4832495/)

Esto se visualiza así:

Emoji smiley Imagen con licencia de Pixabay

Podemos usar el atributo style para llevar la imagen a la izquierda o derecha del párrafo:

Emoji smiley.

Imagen con licencia de Pixabay

La propiedad de estilo float determina si la imagen debe mostrarse a la izquierda o derecha del texto:

<img src="../img/Smiley.png" width="150" height="150" style="float:right"> 

Cambiar right por left si la queremos a la izquierda.

Imágenes como enlaces

Hay ocasiones en las que queremos que, al pulsar sobre una imagen, haga de enlace a otro documento o sección. Podemos combinar ambas sintaxis, la de los enlaces y la de las imágenes. Basta con escribir un enlace y, en lugar del texto a mostrar, poner una imagen.

En formato markdown, en lugar de:

[  texto  ](URL enlazada)

escribimos:

[  ![](archivo_de imagen)  ](URL enlazada)

Y en formato HTML, en lugar de:

<a href="URL enlazada">
   texto 
</a> 

escribimos:

<a href="URL enlazada"> 
   ![](../img/nombre_archivo.jpg) 
</a> 

Notas a pie de página

Una nota a pie de página genera un pequeño enlace numerado¹ en el texto. Al pulsar con el ratón, lleva al lector al texto de la nota a pie de página.

La etiqueta de la nota a pie de página se escribe de manera similar a una referencia de enlace con un símbolo ^ por delante:

Esto es un ejemplo[^aaa] y esto es otro[^bbb].

y en algún lugar, fuera del párrafo, definimos el texto de las notas:

[^aaa]: Texto de la nota 1
[^bbb]: Texto de la nota 2

La numeración se genera automáticamente, basada en el orden en que se escriben las etiquetas.

1. Texto a mostrar ↩

Tablas

Las tablas son bloques de datos organizados en forma de filas y columnas:

En formato markdown, las tablas se escriben de la siguiente forma:

|Posición | País            | Población (en millones)     |
|:--------|:----------------|----------------------------:|
|1        | India           | 1.417 MM                    |
|2        | China           | 1.406 MM                    |
|3        | Estados Unidos  |   341 MM                    |
|4        | Indonesia       |   286 MM                    |
|5        | Pakistán        |   256 MM                    |
|6        | Nigeria         |   236 MM                    |
|7        | Brasil          |   213 MM                    |
|8        | Bangladés       |   177 MM                    |
|9        | Rusia           |   146 MM                    |
|10       | México          |   131 MM                    |

Deben separarse de otros bloques como hacemos con los párrafos, con una línea en blanco antes y después de la tabla. La cabecera se separa del resto de la tabla con guiones -, y las columnas se delimitan con barras verticales |. Las barras en los extremos izquierdo y derecho de la tabla son opcionales:

Posición | País            | Población (en millones)
:--------|:----------------|----------------------------:
1        | India           | 1.417 MM
2        | China           | 1.406 MM
3        | Estados Unidos  |   341 MM
4        | Indonesia       |   286 MM
5        | Pakistán        |   256 MM
6        | Nigeria         |   236 MM
7        | Brasil          |   213 MM
8        | Bangladés       |   177 MM
9        | Rusia           |   146 MM
10       | México          |   131 MM

El carácter de dos puntos : en la línea que separa las cabeceras es opcional, e indica la alineación de cada columna:

| Columa 1  | Columna 2 | Columna 3 |
|:----------|:---------:|----------:|
| izquierda | centrado  |   derecha |
|           |           |           |
|           |           |           |
|           |           |           |

No es obligatorio que las barras verticales estén alineadas (aunque resultaría más facil de editar):

Posición | País | Población (en millones) 
---|-----|--------------
1  | India    | 1.417 MM  
2  | China    | 1.406 MM  
3  | Estados Unidos  |   341 MM  
4  | Indonesia  |   286 MM     
5  | Pakistán  |   256 MM      
6  | Nigeria   |   236 MM      
7  | Brasil    |   213 MM      
8  | Bangladés  |   177 MM     
9  | Rusia      |   146 MM     
10 | México     |   131 MM     

No es posible escribir celdas de varias líneas, aunque podemos insertar etiquetas <br> en el texto de las celdas.

Versión HTML

Podemos crear una tabla insertando texto HTML, aunque es más farragoso:

<table>
    <thead>    
        <tr>   <th style="text-align: left" >  Posición                 </th>
               <th style="text-align: left" >  País                     </th>
               <th style="text-align: right">  Población (en millones)  </th>
        </tr>                                  
    </thead>                                   
    <tbody>                                    
        <tr>   <td style="text-align: left" >  1                        </td>
               <td style="text-align: left" >  India                    </td>
               <td style="text-align: right">  1.417 MM                 </td>
        </tr>                                  
        <tr>   <td style="text-align: left" >  2                        </td>
               <td style="text-align: left" >  China                    </td>
               <td style="text-align: right">  1.406 MM                 </td>
        </tr>                                  
        <tr>   <td style="text-align: left" >  3                        </td>
               <td style="text-align: left" >  Estados Unidos           </td>
               <td style="text-align: right">  341 MM                   </td>
        </tr>
    </tbody>
</table>

En resumen:

• La tabla completa se delimita entre etiquetas <table>
• La cabecera de la tabla se delimita entre etiquetas <thead>
• El cuerpo de la tabla se delimita entre etiquetas <tbody>
• Las filas de celdas van dentro de el cuerpo de la tabla, y se delimitan entre etiquetas <tr> (table row)
• Las celdas van dentro de cada fila, y se delimitan entre etiquetas <td> (table data)

¿Que ventaja tiene el formato markdown? Es más sencillo de escribir, pero no cuenta con las capacidades que podemos obtener de HTML mediante atributos. Pero como sucede con los bloques <div>, la sintaxis markdown no tiene efecto dentro de una tabla HTML.

¡Cuidado!

---

Con algunos conversores de markdown me he encontrado con que la sangría, en bloques HTML insertados en el texto, se considera como texto preformateado.

Alineando la tabla

mdBook usa unas hojas de estilos que alinean la tabla de forma centrada en la página. Me gusta ajustar las tablas al margen izquierdo, por lo que en mi archivo theme/estilos.css añado:

table {
  margin-left: 0;
  margin-right: auto;
}

Lo que significa:

• regla de estilo a aplicar a los elementos <table>
• no dejar margen a la izquierda de la tabla
• dejar que el margen derecho se calcule automáticamente

listas de definiciones

Las listas de definiciones sirven para crear glosarios, donde cada término tiene una o varias definiciones. El formato es:

término A
  : Definición del término A. 
    Puede ocupar varias líneas.

término B
  : Definición del término B.
  
  : Una segunda definición
    de varias líneas.

Cada definición debe comenzar con un carácter : sangrado con cero, uno o dos espacios. Las líneas que forman la definición deben alinearse por la izquierda.

El ejemplo anterior muestra:

término A

Definición del término A. Puede ocupar varias líneas.

término B

Definición del término B.

Una segunda definición de varias líneas.

Cuando un término tiene varias definiciones, estas se mostrarán numeradas.

Podemos crear un enlace a cada definición de igual forma que lo haríamos a los párrafos de cabecera. Especificar el archivo donde se encuentra la lista seguido de un carácter # y el término en minúsculas, con los espacios sustituidos por guiones:

Véase [referencia](glosario.md#término-a)

Con lo que tenemos algo así como:

Véase referencia.

las listas de definiciones son una funcionalidad que se puede desactivar con:

[output.html]
definition-lists = false

Atributos

Aunque la versión de markdown usada por mdBook no permite especificar atributos de elementos individuales, como es el caso de los párrafos, si contamos con un recurso particular para las cabeceras. Consiste en añadir, entre llaves, un identificador y las clases a las que pertenece la cabecera:

# Título del capítulo de introducción { #introduccion .clase1 .clase2 }

Texto regular

Esto permite enlazar a este título usando su nuevo identificador:

Pulse [aquí](archivo.md#introduccion)

lo que nos evita tener que usar todo el texto de la cabecera como identificador.

En el ejemplo, también definimos que éste párrafo de título en particular pertenece a las clases “clase1” y “clase2”, lo que nos permite, entre otras cosas, aplicar los estilos definidos para esas clases en una hoja de estilo.

Resaltado de textos fuente

Textos fuente

Ya hemos visto que podemos escribir texto de programas usando párrafos preformateados, donde se respeta el texto sin transformaciones, y se muestra en un tipo de letra monoespaciada:

Ejemplo de programa Python:

    x = 7
    y = 3
    z = x*y*2
    print(z)

Lo que muestra:

Ejemplo de programa Python:

x = 7
y = 3
z = x*y*2
print(z)

Tenemos otro recurso similar. En lugar de sangrar el bloque, delimitarlo al inicio y final del bloque:

```
x = 7
y = 3
z = x*y*2
print(z)
```

Los delimitadores pueden ser tres caracteres backtick ``` o bien tres tildes ~~~:

~~~
x = 7
y = 3
z = x*y*2
print(z)
~~~

Resaltado

Una de las ventajas de los bloques delimitados (fenced code blocks) es que podemos especificar el lenguaje de programación:

```python
x = 7
y = 3
z = x*y*2
print(z)
```

lo que resalta los elementos del programa en diferentes colores:

x = 7
y = 3
z = x*y*2
print(z)

Véase la documentación de mdBook para saber que lenguajes están contemplados.

Rust

mdBook es un programa creado originalmente para desarrollar la documentación del lenguaje de programación Rust. Tiene capacidades orientadas a este lenguaje.

Por ejemplo, si escribimos un ejemplo de programa Rust:

```rust
fn main() {
    let texto = "Hola";
    print!("{}", texto);
}
```

Hemos especificado que se trata del lenguaje Rust. Esto hace que, junto al icono de copiar texto al portapapeles, se añada otro icono para ejecutar el programa. Lo vemos al pasar el ratón por el programa:

fn main() {
    let texto = "Hola";
    print!("{}", texto);
}

En este cuaderno, orientado a los usuarios en general, no abordaremos las funcionalidades específicas del lenguaje Rust.

Emojis y otros caracteres

A veces sucede que tenemos que insertar caracteres especiales 😁 en el texto de un libro. Esto se puede hacer sustituyendo, en el texto fuente, el carácter por su código de referencia:

emoji sonriente: 😁

Lo que se mostrará como:

emoji sonriente: 😁

En realidad, el archivo HTML generado por mdBook mantiene ese código. Es el navegador web quien lo interpretará, mostrando el carácter asociado.

A este tipo de códigos, cada uno de los cuales representa un carácter, se les llama entidades HTML. Las hay de dos tipos:

• Con nombre. Por ejemplo, © se mostrará como el símbolo © del copyright
• Mediante código. El equivalente de © es ©

Ambos formatos producen el mismo resultado. El primero es más fácil de recordar, pero este formato solo existe para algunos caracteres. El código numérico es universal. Todos los caracteres tienen el suyo.

Existen cientos de entidades con nombre, y más de cien mil caracteres con código, por lo que mostrar aquí una tabla completa va más allá del propósito de este cuaderno. En la web existen multitud de recursos para encontrar tablas de entidades HTML.

Veamos algunos ejemplos:

Símbolos matemáticos:

Emojis:

Iconos

Ya hemos visto que, en la cabecera de cada página web, se muestran unos iconos:

mdBook permite que insertemos estos y otros iconos como parte del texto:

Pulse en el icono para imprimir

¿Como lograrlo? Tenemos que insertar una etiqueta <i> seguida de una de cierre:

<i></i>

En principio, las etiquetas <i> son la forma de marcar texto en cursiva, pero mdBook hace un uso particular y las utiliza de esta forma para insertar iconos. Tenemos que asignarle una clase (o varias, depende del icono):

<i class="fas fa-print"></i>

Con lo que lo anterior, queda así:

Pulse en el icono <i class="fas fa-print"></i> para imprimir

¿Como averiguar la clase a la que pertenece cada icono? mdBook los saca de un repositorio llamado Font Awesome. Podemos examinar los iconos disponibles acudiendo a la página de búsquedas.

mdBook solo incluyen iconos de la versión 6, clase regular, solid, y brands; los iconos de pago como la clase light no se contemplan.

Por ejemplo, acudimos a la página mencionada, introducimos un término de búsqueda, por ejemplo, trash. Seleccionamos free y versión 6. En los resultados, seleccionamos el icono que representa una papelera.

En la descripción del icono se nos muestra el texto HTML a poner en nuestro texto:

• <i class="fa-regular fa-trash-can"></i> para el icono
• <i class="fa-solid fa-trash-can"></i> para el icono

Youtube

A diferencia de lo que sucede con las imágenes, la sintaxis markdown no permite incluir vídeos de Youtube. Entre las extensiones de terceros, hay una llamada Embedify que podemos instalar y usar para este propósito.

Alternativamente, veamos como hacerlo mediante HTML.

Supongamos, por ejemplo, que queremos insertar un video sobre un tema cualquiera, por ejemplo la siguiente charla de Richard Stallman, lider del movimiento por el software libre:

Todos los vídeos de Youtube tienen una dirección que incluye una referencia al final de la URL:

https://www.youtube.com/watch?v=eewFTbLWfEE&t=3s

Tomamos esa URL y cambiamos watch por embed/. Obtenemos lo siguiente:

https://www.youtube.com/embed/eewFTbLWfEE

Y para insertarlo en nuestro documento, como haríamos con una imagen, usamos la etiqueta <iframe>:

<iframe 
    src="https://www.youtube.com/embed/eewFTbLWfEE" width=600 height=400>
</iframe>

Lo que hace esta etiqueta es mostrar otra página web dentro de la nuestra. Por ejemplo, para acceder a la wikipedia:

<iframe 
    src="https://es.wikipedia.org" width=750 height=400>
</iframe>

Muestra:

Admoniciones

Una admonición es un bloque de texto destacado que se utiliza para resaltar información importante. Por ejemplo, si escribimos en el archivo markdown:

> **Nota**<hr>
> Esta es una información importante
> que no se debe pasar por alto.

Obtendremos lo siguiente:

Nota

---

Esta es una información importante que no se debe pasar por alto.

mdBook proporciona un estilo especial de admoniciones. Consiste en añadir una primera línea con el tipo de admonición entre corchetes y con un prefijo !

> [!NOTE]
> Información general o de contexto.

> [!TIP]
> Una sugerencia útil o mejor práctica.

> [!IMPORTANT]
> Información clave que no debe perderse.

> [!WARNING]
> Información crítica que destaca un riesgo potencial.

> [!CAUTION]
> Información sobre posibles problemas que requieren precaución.

Lo que muestra:

Note

Información general o de contexto.

Tip

Una sugerencia útil o mejor práctica.

Important

Información clave que no debe perderse.

Warning

Información crítica que destaca un riesgo potencial.

Caution

Información sobre posibles problemas que requieren precaución.

Pero esta funcionalidad tiene una carencia que, en el momento de escribir esto, sigue sin resolverse. No es posible mostrar las cabeceras traducidas a otros lenguajes. Se muestran en inglés: “Note”, “Tip”, “Warning”, etcétera.

Añadiendo iconos

Una alternativa es usar entidades HTML para añadir un icono al título de la admonición:

> <span style="color:red;font-size:2em;font-weight:bold;"> &#9888; </span>
> **¡Cuidado!** <hr>
> Esta es una información importante
> que no se debe pasar por alto.

Lo que muestra:

⚠ ¡Cuidado!

---

Esta es una información importante que no se debe pasar por alto.

Encerramos el carácter &#9888; entre etiquetas <span> para delimitar el bloque al que deseamos aplicar reglas de estilo:

• color rojo
• doble tamaño de texto
• resaltado en negrita

Otra solución es insertar un icono, como se explicó anteriormente:

• = <i class="fa-solid fa-triangle-exclamation"></i>
• = <i class="fa-solid fa-circle-exclamation"></i>
• = <i class="fa-solid fa-circle-info"></i>
• = <i class="fa-regular fa-circle-xmark"></i>
• = <i class="fa-regular fa-lightbulb"></i>
• = <i class="fa-regular fa-circle-check"></i>
• = <i class="fa-solid fa-circle-radiation"></i>

Por ejemplo:

> <span style="font-size:2em; color:red"><i class="fa-solid fa-triangle-exclamation"></i></span>> **¡Cuidado!** <hr>
> Esta es una información importante
> que no se debe pasar por alto.

Lo que muestra:

¡Cuidado!

---

Esta es una información importante que no se debe pasar por alto.

Extensiones

Las carencias de mdBook se pueden solucionar instalando complementos desarrollados por terceras personas.

Estos complementos son programas que, una vez instalados, se ejecutan durante el proceso de conversión a HTML, transformando (preprocesando) el texto markdown. Se denominan “preprocesadores” y hay una lista en la página de mdBook.

Podemos descargar e instalar el complemento mdbook-admonish, que proporciona admoniciones más elaboradas. Pero la instalación de extensiones suele implicar tener que descargar los programas fuente, en formato de texto y compilarlos a formato binario con las herramientas de desarrollo Rust que tengamos en nuestro equipo. Dejaremos esa tarea para los usuarios programadores de Rust.

Incluir ficheros

mdBook tiene una funcionalidad especial, incluir el texto de otro fichero fuente en mitad del contenido de nuestro fichero markdown.

Supongamos que abrimos un Terminal de comandos y ejecutamos:

$ date

En Linux/Mac, esto muestra la fecha y hora:

viernes, 10 de abril de 2026, 15:07:57 CEST

Podemos personalizar la presentación:

$ date "+%d de %B de %Y" 
                   
10 de abril de 2026

O incluso enviar este texto a un fichero (sobreescribiéndolo):

$ date "+%d de %B de %Y" > src/docs/fecha.txt

Con lo que, si ponemos este comando en el script de generación del libro, antes del comando mdBook, tendremos un fichero añadido con la fecha de actualización del libro.

Nota:

---

En Windows, el comando es:

date /t

¿Como beneficiarnos de todo esto? Supongamos que nuestra página principal es:

© 2025 - Mi taller de libros
Fecha de actualización: {{#include fecha.txt}} 

La expresión entre dobles llaves:

{{#include fecha.txt}} 

será sustituida por el contenido del archivo indicado.

Esta posibilidad de incluir el texto de otro fichero tiene muchas posibilidades. Supongamos que estamos escribiendo un manual técnico con ejemplos de programación. Podemos tener dichos ejemplos como archivos en una carpeta aparte, donde los probamos ejecutándolos para ver si producen el efecto deseado. En lugar de copiar el texto de los ejemplos al libro, Los incluimos en el texto:

Veamos el ejemplo 1.1:

```py
{{#include ejemplo11.py}}
```

en lugar de:

Veamos el ejemplo 1.1:

```py
instrucciones del programa
```

Inclusión parcial

Veamos otra posibilidad. Creamos un archivo iconos.txt:

<i class="fa-solid fa-triangle-exclamation"></i>
<i class="fa-solid fa-circle-exclamation"></i>
<i class="fa-solid fa-circle-info"></i>
<i class="fa-regular fa-circle-xmark"></i>
<i class="fa-regular fa-lightbulb"></i>
<i class="fa-regular fa-circle-check"></i>
<i class="fa-solid fa-circle-radiation"></i>

Y para incluir un icono escribimos algo así como:

{{#include iconos.txt:3}} Información importante.

Descripción...

Lo que muestra:

Información importante.

Descripción…

Hemos especificado un nombre de fichero a incluir, seguido de un número de línea, la número 3. Solo se incluirá esa línea:

{{#include iconos.txt:3}}

Podemos incluir ficheros de forma parcial:

• {{#include archivo.txt:2}} - incluir solo línea 2
• {{#include archivo.txt::10}} - desde el principio hasta la línea 10
• {{#include archivo.txt:2:}} - desde la línea 2 hasta el final
• {{#include archivo.txt:2:10}} - desde la línea 2 a la 10

Fórmulas matemáticas

Supongamos que estamos creando un libro que ha de mostrar fórmulas matemáticas:

\[ \mu = \frac{1}{N} \sum_{i=0} x_i \]

Estas ecuaciones se introducen en forma de párrafo separado, comenzando por una secuencia \\[ y terminando con \\]:

\\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\]

Véase que los símbolos matemáticos van precedidos por una barra invertida \. Esta sintaxis se corresponde con un software de creación de formulas llamado MathJax. Tenemos que habilitar esta funcionalidad de mdBook en el archivo book.toml:

[output.html]
mathjax-support = true

Podemos saber más acerca de esta sintaxis examinando la documentación de Mathjax. De todas formas, la sintaxis que usa mdBook no es del todo compatible. De hecho, no se puede usar $$ ... $$ como delimitadores, y las marcas \[ ... \] necesitan una barra invertida adicional para funcionar.

Ecuaciones dentro de un párrafo

Es posible escribir ecuaciones como fragmento de un párrafo. Se delimitan entre \\( y \\). Por ejemplo, \( \int x dx = \frac{x^2}{2} + C \) es una ecuación insertada mediante:

Por ejemplo, \\( \int x dx = \frac{x^2}{2} + C \\) es una ecuación insertada ...

Conversión tipográfica

Algunas secuencias de caracteres se convertirán automáticamente en otros más elegantes. Por ejemplo,

• Tres puntos consecutivos ... se convertirán en un carácter …

• Las comillas " " se convertirán en unas tipográficas de apertura y cierre, “ ”

• Los apóstrofos ' ' se convertirán en unos tipográficos de apertura y cierre, ‘ ’

• Tres guiones consecutivos --- se convertirán en un guión largo.

Esta característica está activada por defecto. Si nos resulta molesta, en el archivo de configuración book.toml podemos desactivarla:

[output.html]
smart-punctuation = false

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.

Subir archivos a Internet

Ahora que tenemos una carpeta con todos los contenidos a subir a Internet, llega el paso final, utilizar algún servidor web que admita 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, y hago uso de un servicio llamado GitHub Pages, que permite publicar la documentación alojada en ese sitio web.

Para subir los documentos utilizo GitHub Desktop, un programa que podemos descargar e instalar en nuestro ordenador, y que sirve para interaccionar con GitHub. Requiere que previamente tengamos instalado Git en nuestro ordenador, como hemos visto en el capítulo anterior.

Nota

---

Probablemente lo más ortodoxo sería añadir al script de creación del libro media docena de comandos git, que ejecuten la sincronización de ficheros entre GitHub y nuestras carpetas, Pero me gusta separar la tarea en dos fases, conversión a HTML y publicación del libro. Y por otra parte, me gusta la comodidad de GitHub Desktop.

Acerca de GitHub

GitHub es una plataforma de desarrollo colaborativo que permite alojar proyectos, tanto personales como comunitarios, utilizando el sistema de control de versiones Git. Cada usuario puede tener uno o varios repositorios, de forma que cada uno de ellos sirve para alojar un proyecto.

Desde junio de 2018, GitHub es propiedad de Microsoft. Aunque esto produjo ciertos recelos iniciales, GitHub continúa siendo una plataforma importante para proyectos de código abierto.

Para registrarnos como usuarios necesitamos una cuenta de correo. Acudimos a la página principal de GitHub, https://github.com, donde veremos dos enlaces:

• Sign In, para acceder si ya tenemos un código de usuario y contraseña
• Sign Up, para crear una nueva cuenta de usuario.

Pulsamos en Sign_Up y seguimos el proceso para crear una cuenta. Se nos pedirá que establezcamos un nuevo nombre de usuario, una contraseña, y se nos pedirá nuestro correo.

Para aprender a manejarnos con GitHub encontraremos los tutoriales en https://docs.github.com/

Iniciar sesión en GitHub

En la página principal de GitHub, https://github.com, pulsamos en el enlace Sign In. Se nos pedirá nuestro nombre de usuario o correo electrónico y la contraseña.

Tras iniciar la sesión, vemos que en todo momento tenemos un icono en la esquina superior derecha con nuestra imagen de usuario. Pulsando sobre ese icono, veremos un menú de opciones. Algunas de ellas son:

• Sign out - cierra la sesión y sale de GitHub
• GitHub docs - documentación de GHitHub
• Settings - configuración de nuestra cuenta
• Your profile - muestra un resumen de nuestra cuenta y repositorios
• Your repositories - lista de repositorios

Creando un repositorio

El primer paso para publicar un libro es crear un repositorio específico para ese propósito. Vamos a tener tantos repositorios como libros

La creación de nuevos repositorios se puede hacer desde la página web de GitHub, o desde GitHub Desktop. En el primer caso, tras iniciar sesión desplegamos el menú de opciones en la esquina superior derecha. Pulsamos en el enlace repositories, lo que nos lleva a una lista de nuestros repositorios, por ahora, vacía. Pulsamos en el botón New.

Se muestra un formulario para introducir los parámetros del nuevo repositorio:

• Nombre del repositorio

• Si es público o privado. Los repositorios privados no tienen mucho sentido si lo que queremos es publicar un libro.

• Si queremos iniciarlo vacío o con tres posibles archivos:

  • README.md
  • .gitignore
  • Licencia - Tipo de licencia aplicable a nuestros contenidos. Ver licencias

  Podemos dejar estos tres archivos sin crear, porque los podemos subir con la documentación.

Una vez dentro del repositorio, en la barra superior tendremos una serie de etiquetas. Las que más vamos a utilizar son:

• Code muestra la lista de archivos en el repositorio. Si tenemos un archivo README.md se muestra su contenido debajo de la lista, como resumen explicativo del repositorio.

• Settings permite configurar el repositorio (¡incluida su eliminación!).

De todas formas, todo lo dicho es puramente ilustrativo. La creación de repositorios la haremos desde GitHub Desktop.

Ramas

GitHub es un portal colaborativo donde un equipo de personas pueden trabajar en el mismo proyecto. Es posible mantener varias versiones de un repositorio, llamadas “ramas”. Al visualizar la lista de archivos, podemos seleccionar la rama (branch) deseada. Por ahora, nos arreglaremos con la rama “main”.

Eliminar repositorio

En GitHub no hay papeleras de reciclaje. La eliminación de un repositorio se hace entrando a ver el contenido del mismo y pulsando en el icono Settings. En la página de configuración, acudir al apartado Danger Zone.

Subida de archivos

Tras instalar GitHub Desktop, lo ejecutamos por primera vez y vemos lo siguiente:

Si no estamos conectados a GitHub en la ventana del navegador, GitHub Desktop nos muestra un botón sign in para hacerlo. Al conectarnos por primera vez se nos pedirá que activemos la autorización para que GitHub Desktop acceda a nuestros repositorios.

Siguiendo con el proceso de configuración, introducimos nuestras credenciales de GitHub:

Una vez configurado, cada vez que iniciemos GitHub Desktop tendremos un resumen de nuestros repositorios. Pulsamos en Add repository from local drive:

En lo sucesivo, podemos hacer todo esto desde el menú File > Add local repository

Tras completar este paso, Github Desktop ha incluido en su lista de repositorios locales a nuestra carpeta con el libro final. Pero todavía no hemos creado nada en el servidor web.

Vemos un resumen del repositorio y sus archivos. En la parte superior izquierda de la ventana tenemos una lista desplegable para seleccionar otros repositorios o crear uno nuevo:

Para hacer la primera subida de archivos, tenemos que cumplimentar la casilla Summary con alguna frase, “primera versión”, “actualización”, o lo que sea. Pulsamos en Commit (tomar nota de los cambios) y seguidamente en Push (publish, publicar).

Al ejecutar Publish por primera vez para un proyecto concreto, se intenta crear el repositorio en nuestra cuenta de GitHub. En la ventana de diálogo de creación del repositorio se nos pregunta:

• Seleccionar Github.com o Enterprise. Escogemos el primero.
• Introducimos el nombre del repositorio a crear. Obtendremos un error si ya existe un repositorio con ese nombre.
• Introducimos una descripción
• Desmarcamos la casilla “keep this code private”

Actualizaciones

Tras la primera subida de documentos, nuestro proyecto sufrirá modificaciones ¡Importante! Nunca debemos modificar los archivos directamente en el repositorio remoto. Hacerlo en el entorno local y subir los cambios, para un mejor control.

Cada vez que abrimos GitHub Desktop y seleccionar un proyecto, veremos un resumen de los archivos que han sufrido modificaciones en nuestro entorno local. ¡Ojo! Aunque hayamos modificado los archivos markdown, lo que aquí se examina es la carpeta con los ficheros HTML finales. No veremos ningún cambio hasta que no ejecutemos el script de conversión.

Para actualizar el repositorio remoto, hacer lo siguiente:

• pulsar en el botón Fetch origin para actualizar la sincronización de cambios entre los entornos local y remoto.

• si se detectan cambios, rellenar la casilla “Summary” con el texto de la operación a realizar. Por ejemplo, “actualización”. En la lista de archivos en el repositorio remoto, los modificados se mostrarán con ese texto.

• pulsar en el botón Commit y seguidamente en Push origin

Configurar como GitHub Pages

Una vez subida la documentación, tenemos que activar el servicio de publicación. En el navegador web, accedemos a GitHub con nuestra contraseña de usuario y verificamos el contenido del repositorio. El contenido del archivo README.md se visualizará como resumen del proyecto.

En la parte superior de la página pulsamos en Settings. Se abre la página de configuración:

• En la barra lateral, pulsar en Pages.
• En el apartado Source seleccionar la única versión (branch) que tenemos: main
• Pulsar en Save

Aparecerá el mensaje:

“Your site is ready to be published at “https://usuario.github.io/repositorio/”.

Pasado un tiempo, si refrescamos la página, veremos el mensaje:

“Your site is live at “https://usuario.github.io/repositorio/”

A la derecha de ese mensaje tenemos un botón Unpublish site para retirar la publicación sin eliminar el repositorio.

Gracias a los servicios de GitHub Pages, nuestra documentación será accesible mediante la URL:

https://usuario.github.io/nombreproyecto/

sustituyendo “usuario” por nuestro nombre de usuario y “nombreproyecto” por el nombre del repositorio.

Nombre de dominio personalizado

Si, en lugar de usuario.github.io queremos usar un nombre personal cuya propiedad hayamos adquirido, la configuración de GitHub Pages tiene un apartado que podemos cumplimentar, Custom domain.

Acceso al repositorio GitHub

Si acudamos al manual oficial de mdBook, veremos que en la barra superior, en la esquina derecha, tenemos dos iconos que todavía no hemos examinado:

• es un enlace al repositorio donde se alojan los contenidos
• permite acceso para editar textos (si tenemos permiso para ello)

Considerando que no vamos a editar los archivos en remoto, podemos de todas formas permitir el acceso al repositorio si lo activamos en el archivo de configuración book.toml, indicando la URL:

[output.html]

git-repository-url = "https://github.com/usuario/repositorio"
git-repository-icon = "fab-github"

Ya hemos visto que los iconos se toman de Fontawesome. Haciendo una búsqueda en su página web, se muestra la forma de insertar el icono en una página HTML. Por ejemplo:

  <i class="fa-brands fa-github"></i>

Si no indicamos nada, se toma por defecto fab-github, lo que muestra el icono de GitHub. ¿Que pasa si no usamos GitHub? Otra opción es fas-code-fork que muestra el icono .

Nota: el nombre de la clase debe comenzar por fa- para iconos estándar, fas- para iconos sólidos, o fab- para iconos brand.

Crear un índice de libros

Como ya hemos visto, salvo que establezcamos otra cosa, todos nuestros libros son accesibles mediante una URL que es algo así como:

https://usuario.github.io/nombrerepositorio/

Pero nos gustaría crear una página especial que sirva de presentación, con una lista de todos nuestros libros. Será accesible bajo el nombre:

https://usuario.github.io/

Es decir, usamos el mismo nombre de dominio que asignamos a nuestros libros, pero sin especificar el nombre de repositorio. Esto se logra creando un repositorio especial cuyo nombre es usuario.github.io, incluyendo los puntos como parte del nombre y cambiando usuario por nuestro nombre.

Por ejemplo, en el caso de este cuaderno:

• Página de proyecto:

  • URL: https://trezebits.github.io/tutorial_mdBook/
  • Repositorio: https://github.com/trezebits/tutorial_mdBook/

• Página principal, con índice de cuadernos:

  • URL: https://trezebits.github.io/
  • Repositorio: https://github.com/trezebits/trezebits.github.io/

Jeckyll

mdBook es un escelente generador de páginas web, pero no es el único. Si subimos archivos markdown directamente, GitHub hace uso internamente de un conversor llamado Jeckyll, más potente que mdBook, pero también más complejo.

Para un proyecto de página única, sin grandes alardes, vamos a hacer uso de Jeckyll.

Página de índice

El primer paso es crear una carpeta de proyecto en nuestro entorno local, por ejemplo, indice/, como haríamos con cualquier libro. Tratándose de un proyecto tan simple, no vamos a tener subcarpetas.

Seguidamente creamos en esa carpeta un archivo .gitignore

Tercer paso. Ejecutamos los comandos…

$ cd /Users/usuario/Documentos/Proyectos/indice
$ git init

Cuarto paso. Creamos en esa carpeta un archivo de texto README.md con una presentación de nuestro portal:

# Mi portal de documentación

Una colección más de libros accesible en <https://usuario.github.io>

Nota: cambiar “usuario” por nuestro nombre en GitHub

Quinto paso: creamos un archivo de configuración llamado _config.yml (nótese el subrayado como prefijo). En lugar del formato TOML que usamos con mdBook, el conversor de Github utiliza un formato llamado YML. El contenido del fichero puede ser algo así como:

title: Mi sitio de libros
theme: jekyll-theme-cayman

El tema representa el esquema de colores a aplicar. Podemos saber más sobre los temas de GitHub en esta página

El último paso es redactar la página principal a mostrar. La llamaremos index.md, y GitHub la convertirá en index.html:

# Mi portal de documentación

Una breve presentación.

Indice de libros:

-   [Tutorial mdBook](<https://usuario.github.io/tutorial_mdBook/>)
-   [Otro libro](<https://usuario.github.io/otro_libro/>)

Ya está. En la carpeta tenemos:

• un archivo .gitignore

• un archivo README.md que servirá de presentación a quienes visiten GitHub

• nuestra futura página web en formato markdown, index.md

• el archivo de configuración config.yml

• una carpeta .git con el control de cambios

• podemos añadir alguna imagen y mostrarla añadiendo en el archivo index.md:

  ![](imagen.jpeg)
  

Con todo esto, abrimos GitHub Pages, pulsamos en el menú File > Add local repository, seleccionamos la carpeta, y subimos su contenido creando un nuevo repositorio usuario.github.io (cambiando usuario por nuestro nombre). Seguidamente, entramos en la página web de GitHub, comprobamos que se han subido los contenidos, pulsamos en el icono settings y lo publicamos en GitHub Pages.

Por supuesto, podemos obtener una página de presentación más elaborada explorando las capacidades de Jeckyll, o bien, creando un libro mdBook de una sola página.