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.