MkDocs llega a los repos de Fedora

MkDocs es una herramienta escrita en Python que nos permite crear un sitio web a partir de archivos de texto escritos en formato Markdown, como su nombre indica el principal objetivo de esta aplicación es ayudarnos a construir una página web con documentación la que puede ser hospedada en cualquier sitio, incluso en hospedajes gratuitos como Read the Docs o Github pages.

MkDocs viene entre las novedades de Fedora 23 y para los impacientes esta este repo copr con paquetes para Fedora 22.

Para instalar MkDocs

En Fedora 22 habilitamos el repo copr:

sudo dnf copr enable williamjmorenor/mkdocs-f22

Instalamos la aplicación:

sudo dnf install mkdocs

Construyendo nuestro primer sitio

Vamos a crear un nuevo proyecto con:

mkdocs new testing

Esto creara una carpeta nueva con el nombre testing, accedemos a ver el contenido de la carpeta

cd testing
tree
├── docs
│   └── index.md
└── mkdocs.yml

Ahora podemos usar una de las características que nos ofrece mkdocs y ver el sitio web que es poder ver una vista previa de nuestro sitio web con:

mkdocs serve

Abrimos un navegador y vamos a http://127.0.0.1:8000 para ver una vista previa de un sitio construido con mkdocs con información de prueba, no hay que cerrar la terminal para no detener el servidor, ahora podemos editar nuestra documentación y cada vez que guardemos un cambio podremos ver como se actualiza nuestra página.

Agregar más paginas a nuestra documentación

Debemos crear un nuevo archivo dentro del directorio /docs (debe tener extención .md).

touch ./docs features.md

Agregamos algo de información al archivo

vi ./docs/features.md

Guardamos los cambios y editamos el archivo mkdocs.yml para agregar nuestro nueva página:

vi mkdocs.yml

Agregamos algo así:

site_name: Mi Documento
pages:
- 'index.md'
- 'features.md'

Al guardar los cambios podemos ver nuestra página con la información actualizada.

Supongamos que deseamos tener mas de un nivel entre nuestra páginas, podemos crear un menu desplegable agregando información como:

site_name: Mi Documento
pages:
- 'index.md'
- 'features.md'
- Versiones:
    - 'Version 0.1': 'v0.1.md'
    - 'Version 0.2': 'v0.2.md'

Por favor noten que para archivos grandes es mas cómodo crear sub directorios para cada tema diferente.

Finalmente veremos como cambiar el tema de nuestra documentación para ello podemos usar uno de los temas incluidos. editamos el archivo mkdocs.yml y agregamos la siguiente linea:

theme: amelia

Donde el tema puede ser cualquiera de los temas que viene incluidos por defecto, pueden ver la lista completa de temas en esta pagina.

Una vez satisfechos con la vista previa del documento generamos el sitio web con:

mkdocs build

Hospedaje

El sitio web generado por mkdocs puede alojarse en prácticamente cualquier sitio, les recomiendo seguir la guía oficial para por ejemplo aprender como alojar documentación de forma gratuita en  Read the Docs.