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 Markdown.

• Web oficial

pip install mkdocs

Para crear un nuevo proyecto:

mkdocs new miproyecto
cd miproyect

Veremos que se ha generado la siguiente estructura:

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

• 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:

mkdocs serve

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

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

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

Incluso anidando ficheros Markdown en varios directorios:

docs/
    index.md
    user-guide/getting-started.md
    user-guide/configuration-options.md
    license.md

mkdocs build

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.

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

theme:
    name: material

• Listado de temas para MkDocs

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

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

pip install mkdocs-material

Para incluir admonitions (mensajes importantes):

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Para traducir al español:

theme:
    name: material
    language: es