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:

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

Teclas de atajo

Tutorial de mdBook

Plantillas

Traduciendo la ventana de ayuda