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.