====== MkDocs ======

Generador de sitios web estáticos escrito en Python y centrado en la construcción de documentación.

La documentación se escribe con la sintaxis [[informatica:markdown|Markdown]].

  * [[https://www.mkdocs.org/|Web oficial]]

===== Instalación =====

<code>
pip install mkdocs
</code>

===== Uso =====

Para crear un nuevo proyecto:

<code>
mkdocs new miproyecto
cd miproyect
</code>

Veremos que se ha generado la siguiente estructura:

<code>
miproyecto/
├── docs
│   └── index.md
└── mkdocs.yml
</code>

  * ''mkdocs.yml'': fichero de configuración.
  * ''docs'': por defecto, el directorio que contendrá la documentación
  * ''index.md'': página con documentación.

Para previsualizar, podemos utilizar el servidor web que incluye mkdocs ejecutando, dentro del proyecto, lo siguiente:

<code>
mkdocs serve
</code>

Eso construirá la documentación y la tendremos accesible desde http://localhost:8000

==== Escribir documentación ====

Lo mínimo es que exista un fichero ''index.md'' dentro del directorio ''docs''. Luego podemos organizar la documentación como queramos:

<code>
miproyecto/
├── docs
│   └── index.md
│   └── pagina2.md
│   └── pagina3.md
</code>

Incluso anidando ficheros Markdown en varios directorios:

<code>
docs/
    index.md
    user-guide/getting-started.md
    user-guide/configuration-options.md
    license.md
</code>
==== Generar sitio estático ====

<code>
mkdocs build
</code>

Esto creará un directorio llamado ''site'' donde se habrá generadon los ficheros necesarios para poder subirlos a cualquier servidor web y servir la documentación.

===== Temas =====

Una vez instalados, se usan indicándolo en el fichero de configuración ''mkdocs.yml'':

<code yaml>
theme:
    name: material
</code>

  * [[https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes|Listado de temas para MkDocs]]

==== Material for MkDocs ====

  * https://squidfunk.github.io/mkdocs-material/

Para instalar este tema (también instala todas las dependencias como el propio MkDocs):

<code>
pip install mkdocs-material
</code>

Para incluir admonitions (mensajes importantes):

<code yaml>
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
</code>

Para traducir al español:

<code yaml>
theme:
    name: material
    language: es
</code>