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.
