MkDocs es un generador de sitios estáticos que está orientado para la creación de documentación de Software. MkDocs está escrito en Python y es muy simple y fácil de configurar e implementar.

Además toda la documentación que tengas que escribir la tienes que hacer en formato Markdown, que nos facilita mucho la vida y nos encanta a los SysAdmins/Developers. Y con todo esto, luego para configurarlo únicamente debes de usar un fichero escrito en YAML.

No solo los desarrolladores tienen que escribir documentación, los SysAdmins más avanzados y más expertos también necesitan documentar instalaciones de Software, configuraciones, etc.

MkDocs es una genial herramienta para hacer todo eso y yo desde hace algunos meses estoy usando y estoy encantado.

Para este tutorial vamos a usar un Debian 9 -como no- y realmente es lo único que vamos a necesitar.

Preparación del servidor

Lo primero que haremos será unos pasos previos antes de instalar MkDocs, para revisar que lo tenemos todo.

Generalmente, Debian ya viene con Python instalado por defecto, así que en una instalación nueva deberíamos de tener Python -quizás varían las versiones-.

$ python --version
Python 2.7.13

Luego tendremos que instalar pip para poder instalar el paquete mkdocs:

apt install python-pip

Y una vez instalado comprobamos la versión:

$ pip --version
pip 9.0.1 from /usr/lib/python2.7/dist-packages (python 2.7)

Listo, ahora ya podemos instalar MkDocs!

Instalación de MkDocs

Pues su instalación es muy sencilla:

pip install mkdocs

Simplemente hay que hacer esto, podemos ver que la versión que tenemos es la siguiente:

$ mkdocs --version
mkdocs, version 1.0.4 from /usr/local/lib/python2.7/dist-packages/mkdocs (Python 2.7)

Creando un proyecto nuevo

Ya podemos crear nuevos proyectos con MkDocs, simplemente tenemos que ejecutar lo siguiente:

$ mkdocs new miproyecto
INFO    -  Creating project directory: miproyecto
INFO    -  Writing config file: miproyecto/mkdocs.yml
INFO    -  Writing initial docs: miproyecto/docs/index.md

Si observamos lo que se ha generado en el directorio miproyecto:

$ ls -lt miproyecto/
drwxr-xr-x 2 root root 4096 Apr 25 15:11 docs
-rw-r--r-- 1 root root   19 Apr 25 15:11 mkdocs.yml

El fichero mkdocs.yml será nuestro fichero de configuración donde tendremos todos los parámetros para configurar nuestra documentación. En el directorio docs tendremos que añadir los ficheros .md con las paginas de la documentación.

Podemos acceder al proyecto ejecutando un comando que cree un servidor web para poder acceder a la pagina. Utiliza el puerto 8000 y normalmente lo hace a localhost, pero se puede modificar la IP de acceso de la siguiente forma:

mkdocs serve -a <IP:PUERTO>

Crear web estática con MkDocs

Con MkDocs tenemos la opción de generar una web estática con toda la documentación que hayamos creado. LO que hace es transformar todo lo escrito en MarkDown y lo pasa a HTML/CSS/JS. Vamos, una web estática de toda la vida.

mkdocs build

Esto te genera la web en la carpeta site:

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /root/miproyecto/site

Con el siguiente contenido:

root@mkdocs:~/miproyecto/site# ls -lt
total 44
-rw-r--r-- 1 root root 6510 Apr 25 15:24 index.html
drwxr-xr-x 2 root root 4096 Apr 25 15:24 search
-rw-r--r-- 1 root root  244 Apr 25 15:24 sitemap.xml
-rw-r--r-- 1 root root  202 Apr 25 15:24 sitemap.xml.gz
-rw-r--r-- 1 root root 5477 Apr 25 15:24 404.html
drwxr-xr-x 2 root root 4096 Apr 25 15:24 css
drwxr-xr-x 2 root root 4096 Apr 25 15:24 fonts
drwxr-xr-x 2 root root 4096 Apr 25 15:24 img
drwxr-xr-x 2 root root 4096 Apr 25 15:24 js

Configuración básica de mkdocs.yml

Si modificamos el fichero de configuración, encontraremos que únicamente está configurado el parámetro site_name:

$ cat mkdocs.yml
site_name: My Docs

Aquí podremos añadir diferentes parámetros para configurar nuestra documentación, por ejemplo, un menú:

$ cat mkdocs.yml
site_name: Mi documentación

nav:
   - Home: index.md
   - About: about.md

Dentro de myproyecto/docs tendremos que crear un fichero llamado about.md. Tras crear el contenido de esa página, podremos volver a iniciar el servidor:

También podemos añadir un parámetro para indicar el tema que va usar mkdocs:

site_name: MkLorum
nav:
    - Home: index.md
    - About: about.md
theme: readthedocs

Y ahora se verá de esta forma:

Dependiendo del tema que instalemos tendremos otros parámetros para configurar. Por el momento vamos a dejar esto aquí no sin antes animaros a husmear todo lo que podáis la documentación que tiene Mkdocs.

Conclusión

En el siguiente tutorial veremos la instalación de plugins, de temas y la configuración de ellos. Además también repasaremos la sintaxis de algunos de los plugins

Haz que cada palabra cuente: tu donación nos inspira a seguir creando contenido. Accede al apartado de Donación para hacer tu aportación