Mkdocs, crea documentación gracias a este software de código abierto

En el siguiente artículo vamos a echar un vistazo a Mkdocs. Si desarrollas software y buscas una plataforma para crear documentación para uno de tus proyectos. O si trabajas en una empresa que necesita crear una documentación interna para el personal. Incluso si eres un usuario avanzado que quiere guardar algunas notas. MkDocs es una herramienta que deberías probar.

Este software es un generador de sitios estáticos orientado a la creación de plataformas de documentación. Es bastante simple, bonito de ver y fácil de configurar y desplegar. Está escrito en Python y simplemente requiere que crees tus archivos en formato Markdown. Después, utilizando un solo archivo de configuración YAML, puedes generar un sitio web estático que funcione para ti.

A continuación vamos a ver lo fácil que es obtener un sitio web completo de documentación utilizando MkDocs. Hay muchos otros generadores de sitios estáticos similares, pero este tiene una configuración e implementación de las más sencillas.

Un usuario normal también podría usar este software para crear una plataforma local para tomar notas para sí mismo o cualquier otra cosa similar.

Instalar MkDocs

Instalar localmente

Vamos a ver que instalar MkDocs es bastante fácil. Podremos instalarlo utilizando pip. Solo hay que abrir una terminal (Ctrl+Alt+T) y escribir en ella:

pip install mkdocs

Tras la instalación, en tu directorio de trabajo, ejecuta el siguiente comando para inicializar un sitio:

mkdocs new mkdocspro

Y después, para empezar a servirlo ejecuta:

cd mkdocspro

mkdocs serve

A continuación, ya puedes ir a localhost:8000 (o tu dirección IP / nombre de host con el puerto 8000) para ver cómo funciona MkDocs.

Instalar en tu servidor nginx

Dado que este es un generador de sitio estático, no se necesita un motor de back-end como PHP o Python. Podrás implementar el proyecto MkDocs en tu servidor web (nginx, apache2) en un minuto. Por ejemplo, aquí está la configuración del host virtual nginx:

server {
        server_name ejemplo.com;

        root /var/www/mkdocspro/sitio;
        index index.html;

        location / {
                try_files $uri $uri/ =404;
        }
}

Reemplaza ejemplo.com con el dominio que tienes en tu servidor. También tendrás que cambiar /var/www/mkdocspro/sitio por la ruta de la subcarpeta del sitio en tu servidor. Después solo nos queda reiniciar nginx con el siguiente comando:

sudo service nginx restart

Ahora puedes dirigirte a ejemplo.com y verlo funcionar.

Instala otro tema en Mkdocs

El tema predeterminado de Mkdocs no es especialmente bueno. Pero puedes instalar otro en un minuto. Un ejemplo de instalación de otro tema, será el siguiente. Con el que vamos a instalar el tema material:

pip install mkdocs-material

Tras la instalación, para activar el tema, habrá que editar su archivo mkdocs.yml y hacerlo similar a este. Se pueden agregar algunas opciones:

site_name: Proyecto MkDocs
site_url: 'http://ejemplo.com'
repo_url: 'https://github.com/nombreusuario/proyectourlongithub'
edit_uri: edit/master
site_description: 'Aquí una descripción corta.'
google_analytics: ['UA-xxxxxxxxx-x', 'ejemplo.com']
extra:
  favicon: 'https://ejemplo/favicon.png'
  social:
    - type: 'github'
      link: 'https://github.com/xxxxxx'
    - type: 'facebook'
      link: 'https://facebook.com/xxxxxxx'
    - type: 'twitter'
      link: 'https://twitter.com/xxxxxxx'
  disqus: 'minombredisqus'
  theme: 'material'

Las opciones son bastante claras. Pero aquí van algunas explicaciones:

• repo_url: es la URL del repositorio de Git. Si planeas integrar Git directamente en tu proyecto de MkDocs, puedes usar esta opción para permitir que las personas editen las páginas o bifurquen el proyecto.
• edit_uri: Este es el postfix para editar páginas en GitHub. Puedes cambiarlo si estás usando GitLab o GitBucket.
• google_analytics: No hay panel de control para MkDocs. Por lo tanto, para saber quién visita tu sitio web, deberás utilizar Google Analytics. Esta opción te va a permitir insertar su número de seguimiento para asociar tu cuenta con el sitio web.
• disqus: Si quieres habilitar el sistema de comentarios de Disqus en el sitio web, puedes insertar tu nombre corto aquí.
• tema: El nombre del tema que quieres usar. Tendrás que instalarlo previamente, como acabamos de hacer con el tema material. Este será el nombre que utilizaremos en el ejemplo.

Ver los cambios del nuevo tema

Tras guardar el archivo, ejecuta mkdocs build dentro de la carpeta mkdocsproject. Tu sitio web adoptará la apariencia y el estilo predeterminados del tema Material:

Importante: asegurate de ejecutar mkdocs build siempre después de cada modificación que realices en los archivos. De lo contrario no verás ningún cambio.

Hay muchos otros temas y opciones para configurar este software. Puede consultarlos en la documentación oficial de MkDocs. Aquí hay una lista de posibles opciones que podemos utilizar.