Guía Markdown de MkDocs

MkDocs es un generador de sitios web estáticos creado con el objetivo de que puedas documentar tu proyecto con Markdown y luego generar un sitio web estático con los archivos que hayas creado.

Acerca de MkDocs

MkDocs es una herramienta open source desarrollada con Python. Tiene una gran comunidad detrás que mejora y da soporte a la herramienta.

Cuando creas tu proyecto podrás previsualizar el sitio web mientras trabajas, ya que MkDocs viene configurado por defecto para que el navegador se refrescque con cada cambio en los archivos.

MkDocs dispone de varias extensiones y de varios temas que puedes encontrar aquí. Además, también podrás crear tu propio tema.

MkDocs usa el procesador de Markdown Python-Markdown.

Instalación de McDocs

Podrás instalar MkDocs con varios gestores de paquetes, como apt-get, hombebrew, chocolatey, yum o dfn.

Si lo prefieres, puedes instalar MkDocs manualmente. Para ello necesitarás tener el gestor de paquetes PIP en tu sistema. Si no tienes PIP instalado, consulta el tutorial de instalación de PIP. Alternativamente, en caso de que tengas Python instalado en tu sistema, abre una ventana de línea de comandos e instala PIP con este comando:

python get-pip.py

En caso de que PIP no esté actualzado, actualízalo con este comando:

pip install --upgrade pip

Para instalar MkDocs basta con que uses este comando:

pip install mkdocs

Finalmente, comprueba si la instalación se ha realizado con éxito ejecutando el comando mkdocs con el flag --version:

$ mkdocs --version
mkdocs, version 0.15.3

Crea un proyecto con McDocs

Para crear un proyecto con MkDocs basta con que abras una ventana de línea de comandos y te posiciones en el directorio en el que quieras crear el proyecto. Luego ejecuta este comando, reemplanzando mi-proyecto por el nombre del proyecto:

mkdocs new mi-proyecto

Luego accede al proyecto con el comando cd:

cd new mi-proyecto

Seguidamente, una vez en el directorio del proyecto, inicia el servidor de desarrollo con este comando:

mkdocs serve

Como resultado podrás ver la URL del proyecto:

INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

Si accedes a la URL http://127.0.0.1:8000 o a la que se muestre en la terminal usando tu navegador, podrás ver el proyecto en funcionamiento.

Soporte Markdown

MkDocs soporta los elementos de la sintaxis Markdown que ves en la siguiente tabla:

Soporte adicional

MkDocs soporta muchas otras funcionalidades gracias a sus extensiones. Además, también puedes activar los mensajes contextuales en tu proyecto para así mostrar anotaciones, avisos o mensajes de ayuda. Pudes encontrar la sintaxis de estos elementos en GitHub.

Alternativas a MkDocs

Existen también otros generadores de sitios web estáticos que te permitirán crear documentaciones, como por ejemplo Docusaurus.

Más información

Si quieres, puedes consultar los siguientes enlaces para obtener más información acerca de MkDocs:

• Web: Accede a la Web de MkDocs
• Guía: Accede a la Guía de MkDocs
• Repositorio: Accede al Repositorio de MkDocs