Archivos externos

Incluir archivos

La extensión Snippets permite incluir texto de otros ficheros en el actual. Supongamos que tenemos dos archivos. Si en una línea del documento 1 escribimos:

Texto del documento 1.

--8<-- "miArchivoExterno2.txt"

Más texto del documento 1.

al llegar a la marca --8<-- MkDocs sustituirá esa línea por el texto del fichero externo indicado, como paso previo antes de transformar markdown a HTML. Lo que se va a procesar será el resultado de la inclusión:

Texto del documento 1.

Texto del documento2.

Más texto del documento 1.

El nombre del fichero ha de ir entrecomillado y precedido por la marca --8<--. Su ubicación se establece con referencia al directorio raíz de proyecto (allí donde se encuentra mkdocs.yml:

--8<-- "docs/mifichero.md"

Esta característica solo funcionará si esta marca se escribe en línea aparte (no tiene efecto como parte de un párrafo). Debemos activar en el archivo de configuración mkdics.yml:

markdown_extensions:
  - pymdownx.snippets

Acerca de la marca --8<--

Curiosa marca --8<--, ¿no? En realidad representa la opción de cortar y pegar texto. Se trata de unas tijeras 8< entre guiones.

Problema

Al redactar este cuaderno, me he encontrado con que el texto --8<-- no se mostraba como parte de los ejemplos, ya que snippets lo interpretaba como mi intención de insertar un archivo. Podemos desactivar el efecto anteponiendo un punto y coma ;--8<--. Snippets respetará la marca como texto regular y ocultará el carácter de punto coma.

¿Como resuelve snippets la inclusión de archivos? hay dos aspectos a tener en cuenta:

• Toda inclusión se hace antes de la transformación a HTML. La sintaxis markdown de los archivos incluidos pasará a formar parte del conjunto a procesar.

• El archivo externo incluido puede, a su vez, tener otras marcas --8<--, lo que hace que se produzca una inclusión de archivos en cascada, es decir, nuestro archivo actual incluye al archivo X, este al archivo Y, y este a su vez, al archivo Z.

  Esto puede dar lugar a un círculo cerrado, cuando X incluye a Y, este a Z, y este último a X. Snippets lo evita ignorando la inclusión de archivos que ya han sido incluidos.

Veamos a continuación algunas utilidades de la extensión Snippets.

Para incluir texto fuente

Supongamos que estamos creando un documento con cientos de ejemplos de programación. Podemos poner esos programas en ficheros aparte, para probar que se ejecutan correctamente, y pedir a MkDocs que los incluya en el texto del manual:

```java title="Programa de ejemplo 1.1"

--8<-- "ejemplos/programa1.1.txt"

```

La carpeta hace referencia a una que cuelga del directorio raíz del proyecto. No ponemos los archivos en la carpeta /docs para evitar que se generen archivos HTML para cada fichero. Solo queremos incluirlos en el documento principal.

Para crear un glosario de abreviaturas

En el capítulo dedicado al texto emergente hemos visto la extensión Abbreviations, cuyo uso permite que, si en el texto hay abreviaturas, al pasar el puntero del ratón sobre las mismas, se muestre su significado. Por ejemplo:

Los formatos web están coordinados por el consorcio W3C.

Vemos que la palabra W3C se muestra en un tipo de letra especial y, al pasar el ratón por encima, se muestra su significado al cabo de un breve lapso de tiempo.

¿Que pasa si queremos definir las mismas abreviaturas en varias páginas del documento? Podemos crear un archivo glosario.md con las definiciones de abreviaturas:

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

y de esta forma, todos los términos incluidos en el glosario podrán ser mostrados en cualquier documento con la posibilidad de visualizar su significado al pasar el ratón por encima.

Pero esto tiene un inconveniente. Al final de cada archivo markdown tenemos que escribir:

--8<-- "glosario.md"

Podemos evitarlo si configuramos una lista de archivos a incluir automáticamente en todos los documentos del proyecto:

markdown_extensions:
  - pymdownx.snippets:
      auto_append:
        - include/glosario.md

Para crear una lista de enlaces

Nótese que, a lo largo de las páginas de este cuaderno, incluimos enlaces varios a las mismas páginas:

• Material for MkDocs
• MkDocs
• PyMdown

Al final de cada documento tenemos que añadir las referencias:

[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material
[MkDocs]: https://www.mkdocs.org
[PyMdown]: https://facelessuser.github.io/pymdown-extensions/

lo que se puede evitar creando un archivo de enlaces y configurando mkdocs.yml:

markdown_extensions:
    - pymdownx.snippets:
          auto_append:
             - include/enlaces.md

Para insertar la fecha de creación

Para compilar el proyecto, podemos crear un script de comandos:

cd /micarpeta/miproyecto
date "+Fecha última actualización: %d-%b-%Y" > ./include/fecha.md
mkdocs build

El funcionamiento del comando "date" depende del sistema operativo. En mi caso, tratándose de un Mac, se crea un archivo con una línea de texto:

Fecha última actualización: 03-ene-2025

En la página de portada incluimos:

--8<-- "include/fecha.md"

y de esta forma, siempre que compilemos el proyecto se mostrará la fecha de actualización en la primera página.