MkDocs es un generador de sitios estáticos que está orientado a la creación de proyectos de documentación. Los documentos se escriben en formato Markdown y el sitio se configura mediante un único archivo de configuración YAML. Es tan fácil de usar que parece pensado para motivar a aquellas personas que son reacias a documentar.
A partir de la documentación este magnífico generador permite crear sitios estáticos HTML que se pueden alojar en un servidor web.
Para configurar la apariencia de un sitio se puede configurar un tema o crear uno original que se adapte a una imagen corporativa o a un diseño propio.
MkDocs incorpora un servidor de desarrollo que permite obtener una vista previa de la documentación a medida que se va creando. Dicha documentación se carga y actualiza automáticamente en el navegador web cada vez que cambia.
Tanto en el servidor de desarrollo como en el sitio estático HTML que se genera se incluye un buscador que hará las delicias de los usuarios.
A partir de la documentación este magnífico generador permite crear sitios estáticos HTML que se pueden alojar en un servidor web.
Para configurar la apariencia de un sitio se puede configurar un tema o crear uno original que se adapte a una imagen corporativa o a un diseño propio.
MkDocs incorpora un servidor de desarrollo que permite obtener una vista previa de la documentación a medida que se va creando. Dicha documentación se carga y actualiza automáticamente en el navegador web cada vez que cambia.
Tanto en el servidor de desarrollo como en el sitio estático HTML que se genera se incluye un buscador que hará las delicias de los usuarios.
Instalación de MkDocs
MkDocs se puede instalar con el gestor de paquetes del sistema operativo (apt, yum, etc.), o bien, si el gestor no cuenta con un paquete específico, con el instalador pip, con Python 2.x/3.x
Para instalar MkDocs con el gestor de paquetes apt ejecutar en la consola:
$ sudo apt install mkdocs
Para instalar MkDocs con el instalador pip:
$ pip install mkdocs
Para conocer la versión instalada de MkDocs:
$ mkdocs --version
Para obtener una lista completa de todos los comandos:
$ mkdocs --help
Para instalar MkDocs con el gestor de paquetes apt ejecutar en la consola:
$ sudo apt install mkdocs
Para instalar MkDocs con el instalador pip:
$ pip install mkdocs
Para conocer la versión instalada de MkDocs:
$ mkdocs --version
Para obtener una lista completa de todos los comandos:
$ mkdocs --help
Creando un proyecto nuevo de documentación
Un proyecto de documentación en MkDocs es un conjunto de documentos en formato MarkDown (.md) accesibles desde una opción del menú, desde enlaces que incluyen los propios documentos o desde el buscador de documentos que incorpora el propio sistema.
Los documentos de un proyecto pueden incluir imágenes, enlaces a otros tipos de archivos y enlaces tanto a páginas del propio proyecto como externas.
Para crear un proyecto de documentación ejecutar en la consola:
$ mkdocs new nombre-proyecto
Durante el proceso de creación se mostrará en pantalla la siguiente información:
INFO - Creating project directory: nombre-proyecto
INFO - Writing config file: nombre-proyecto/mkdocs.yml
INFO - Writing initial docs: nombre-proyecto/docs/index.md
Si todo ha ido bien el comando creará una carpeta con el nombre del proyecto con un archivo de configuración llamado mkdocs.ylm y una carpeta llamada docs para los documentos que se irán agregando al proyecto; que en primera instancia incluye un primer documento llamado index.md con un contenido de ejemplo.
Para acceder al directorio del proyecto:
$ cd nombre-proyecto
Los documentos de un proyecto pueden incluir imágenes, enlaces a otros tipos de archivos y enlaces tanto a páginas del propio proyecto como externas.
Para crear un proyecto de documentación ejecutar en la consola:
$ mkdocs new nombre-proyecto
Durante el proceso de creación se mostrará en pantalla la siguiente información:
INFO - Creating project directory: nombre-proyecto
INFO - Writing config file: nombre-proyecto/mkdocs.yml
INFO - Writing initial docs: nombre-proyecto/docs/index.md
Si todo ha ido bien el comando creará una carpeta con el nombre del proyecto con un archivo de configuración llamado mkdocs.ylm y una carpeta llamada docs para los documentos que se irán agregando al proyecto; que en primera instancia incluye un primer documento llamado index.md con un contenido de ejemplo.
Para acceder al directorio del proyecto:
$ cd nombre-proyecto
Examinando los documentos iniciales
Cuando se crea un proyecto el archivo de configuración mkdocs.ylm sólo contiene una línea con la opción site_name para el nombre del sitio:
site_name: My Docs
Por otro lado, el contenido del archivo index.md, que se encuentra en el directorio docs, está escrito con Markdown. Este archivo incluye un título con un texto de bienvenida al que sigue un enlace a la documentación oficial del proyecto Mkdocs; un título de segundo nivel con el literal "Commands" al que sigue la lista básica de comandos de MkDocs y, finalmente, un apartado con el título de segundo nivel "Project Layout" que muestra la estructura básica de carpetas y archivos de un proyecto de documentación:
site_name: My Docs
Por otro lado, el contenido del archivo index.md, que se encuentra en el directorio docs, está escrito con Markdown. Este archivo incluye un título con un texto de bienvenida al que sigue un enlace a la documentación oficial del proyecto Mkdocs; un título de segundo nivel con el literal "Commands" al que sigue la lista básica de comandos de MkDocs y, finalmente, un apartado con el título de segundo nivel "Project Layout" que muestra la estructura básica de carpetas y archivos de un proyecto de documentación:
# Welcome to MkDocs
For full documentation visit [mkdocs.org](https://mkdocs.org).
## Commands
* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs help` - Print this help message.
## Project layout
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
Este contenido será sustituido por el que se quiera incluir en la primera página de un proyecto de documentación.
Comenzando a trabajar con el servidor de desarrollo
MkDocs incorpora un servidor de desarrollo integrado que permite obtener una vista previa de la documentación en un navegador Internet mientras se trabaja.
Para iniciar el servidor es necesario encontrarse en el directorio del archivo de configuración mkdocs.yml y, después, ejecutar el siguiente comando:
$ mkdocs serve
Durante el proceso de inicio se muestra en la consola la siguiente información:
INFO - Building documentation...
INFO - Cleaning site directory
[I 190531 10:59:18 server:298] Serving on http://127.0.0.1:8000
[I 190531 10:59:18 handlers:59] Start watching changes
[I 190531 10:59:18 handlers:61] Start detecting changes
[I 190531 10:59:20 handlers:132] Browser Connected ...
A continuación, para mostrar la página de inicio del proyecto hay que acceder a la siguiente dirección http://127.0.0.1:8000/ desde un navegador Internet.
El navegador mostrará en la parte superior una barra que, de momento, sólo incluirá el nombre del sitio obtenido del fichero de configuración y un buscador. Más adelante, haremos mención al modo de incluir un menú de navegación que permita acceder a otros documentos o contenidos del proyecto.
A continuación, se cargará la primera página del proyecto (index.md) con su contenido dividido en dos áreas:
El servidor de desarrollo carga de forma automática la documentación cada vez que cambia el archivo de configuración o el contenido de los archivos de la documentación. Esto es fácil de comprobar con la página cargada en el navegador, modificando o añadiendo algún texto y guardando los cambios efectuados. Dichos cambios serán aplicados de forma inmediata en el navegador.
Para detener el servidor presionar en la consola la combinación de teclas [Control+C]
Para iniciar el servidor estableciendo una IP y un puerto diferentes:
$ mkdocs serve -a Dirección-IP:Número-Puerto
Para obtener información de ayuda de otras opciones disponibles:
$ mkdocs serve --help
Para iniciar el servidor es necesario encontrarse en el directorio del archivo de configuración mkdocs.yml y, después, ejecutar el siguiente comando:
$ mkdocs serve
Durante el proceso de inicio se muestra en la consola la siguiente información:
INFO - Building documentation...
INFO - Cleaning site directory
[I 190531 10:59:18 server:298] Serving on http://127.0.0.1:8000
[I 190531 10:59:18 handlers:59] Start watching changes
[I 190531 10:59:18 handlers:61] Start detecting changes
[I 190531 10:59:20 handlers:132] Browser Connected ...
A continuación, para mostrar la página de inicio del proyecto hay que acceder a la siguiente dirección http://127.0.0.1:8000/ desde un navegador Internet.
Aspecto inicial de un proyecto
El navegador mostrará en la parte superior una barra que, de momento, sólo incluirá el nombre del sitio obtenido del fichero de configuración y un buscador. Más adelante, haremos mención al modo de incluir un menú de navegación que permita acceder a otros documentos o contenidos del proyecto.
A continuación, se cargará la primera página del proyecto (index.md) con su contenido dividido en dos áreas:
- En el área de la izquierda se muestra una lista de opciones construida con las líneas de títulos y subtítulos que existen en el documento index.md (son las que tienen al comienzo #, ##,...).
- Y en el área derecha se muestra el texto del documento debidamente formateado.
El servidor de desarrollo carga de forma automática la documentación cada vez que cambia el archivo de configuración o el contenido de los archivos de la documentación. Esto es fácil de comprobar con la página cargada en el navegador, modificando o añadiendo algún texto y guardando los cambios efectuados. Dichos cambios serán aplicados de forma inmediata en el navegador.
Para detener el servidor presionar en la consola la combinación de teclas [Control+C]
Para iniciar el servidor estableciendo una IP y un puerto diferentes:
$ mkdocs serve -a Dirección-IP:Número-Puerto
Para obtener información de ayuda de otras opciones disponibles:
$ mkdocs serve --help
La barra de navegación
En la barra de navegación de la parte superior de un proyecto se puede incluir un menú de opciones para facilitar el acceso a la documentación. La definición de este menú se hace incluyendo la opción nav en el archivo de configuración mkdocs.yml. Las opciones de un menú pueden tener varios niveles y cada opción final puede cargar un documento del proyecto o un contenido externo.
Si no se ha configurado ningún menú y MkDocs detecta que se han agregado nuevos documentos a la carpeta docs construirá su propio menú basándose en el texto de las líneas de títulos que tengan dichos documentos. También, incluirá opciones para navegar al documento siguiente y al previo.
Lo razonable es crear otras carpetas dentro de la carpeta docs para agrupar documentos con el mismo tipo de contenido. También, es recomendable crear una carpeta para las imágenes (img) y otras que sirvan para localizar archivos del mismo tipo que interesen estar localizados (como archivos .PDF); y que se van a enlazar desde las distintas opciones del menú o desde otros documentos. Establecer cierto orden siempre ayuda a agilizar el trabajo.
A continuación un ejemplo de archivo de configuración con un menú con distintos niveles de opciones que enlazan documentos MarkDown y un PDF:
Si no se ha configurado ningún menú y MkDocs detecta que se han agregado nuevos documentos a la carpeta docs construirá su propio menú basándose en el texto de las líneas de títulos que tengan dichos documentos. También, incluirá opciones para navegar al documento siguiente y al previo.
Lo razonable es crear otras carpetas dentro de la carpeta docs para agrupar documentos con el mismo tipo de contenido. También, es recomendable crear una carpeta para las imágenes (img) y otras que sirvan para localizar archivos del mismo tipo que interesen estar localizados (como archivos .PDF); y que se van a enlazar desde las distintas opciones del menú o desde otros documentos. Establecer cierto orden siempre ayuda a agilizar el trabajo.
A continuación un ejemplo de archivo de configuración con un menú con distintos niveles de opciones que enlazan documentos MarkDown y un PDF:
site_name: Mi proyecto
nav:
- Inicio: 'index.md'
- Tutorial:
- 'Instalación':
- 'Introducción': tutorial/introduccion.md
- 'Escenarios': tutorial/escenarios.md
- 'Instalación': tutorial/instalacion.md
- 'Guía':
- 'Primeros Pasos': tutorial/primeros_pasos.md
- 'Referencia': tutorial/referencia.md
- 'Descargar PDF': PDF/guia.pdf
- Ayuda:
- 'Contactar': ayuda/contactar.md
- 'Comunidades': ayuda/comunidades.md
- 'Acerca de': ayuda/acercade.md
Como puede observarse todas las rutas de los documentos que se indican son relativas. Así deben expresarse también cuando se incluyan en los propios documentos.
También, cuando se define un menú hay que tener en cuenta que cualquier página que exista en la carpeta docs que no se incluya en alguna de las opciones del menú quedará oculta para el usuario, a no ser que sea enlazada desde algún documento.
Para mostrar el menú de opciones del ejemplo, copiar el código al archivo de configuración de un proyecto e iniciar el servidor de desarrollo. Para que los enlaces a los documentos carguen algún contenido crear las carpetas y los documentos necesarios con algún texto de ejemplo. Es posible generar textos aleatorios para pruebas en el sitio Lorem Ipsum.
Por último, la barra superior incluye un buscador que permite acceder de forma rápida a los documentos de un proyecto. El buscador presentará un resumen con enlaces a los documentos o secciones que contengan el texto buscado, a medida que se escribe.
También, cuando se define un menú hay que tener en cuenta que cualquier página que exista en la carpeta docs que no se incluya en alguna de las opciones del menú quedará oculta para el usuario, a no ser que sea enlazada desde algún documento.
Para mostrar el menú de opciones del ejemplo, copiar el código al archivo de configuración de un proyecto e iniciar el servidor de desarrollo. Para que los enlaces a los documentos carguen algún contenido crear las carpetas y los documentos necesarios con algún texto de ejemplo. Es posible generar textos aleatorios para pruebas en el sitio Lorem Ipsum.
Buscador
Por último, la barra superior incluye un buscador que permite acceder de forma rápida a los documentos de un proyecto. El buscador presentará un resumen con enlaces a los documentos o secciones que contengan el texto buscado, a medida que se escribe.
Cambiando la apariencia del proyecto
Para cambiar la apariencia del proyecto lo más rápido es incluir en el archivo de configuración la opción theme con el nombre de alguno de los temas disponibles (mkdocs, readthedocs, windmill, etc).
MkDocs permite también desarrollar un tema propio. Hay información relacionada con la personalización de los proyectos en el sitio oficial.
MkDocs también adapta las páginas de un proyecto a la pantalla del dispositivo que se esté utilizando en cada caso:
Finalmente, comentar que se puede sustituir el icono predeterminado del proyecto por otro personalizado (favicon.ico) copiando el icono a la carpeta de imágenes (img) del proyecto.
Proyecto basado en el tema MkDocs
Proyecto basado en el tema Windmill
MkDocs permite también desarrollar un tema propio. Hay información relacionada con la personalización de los proyectos en el sitio oficial.
MkDocs también adapta las páginas de un proyecto a la pantalla del dispositivo que se esté utilizando en cada caso:
Finalmente, comentar que se puede sustituir el icono predeterminado del proyecto por otro personalizado (favicon.ico) copiando el icono a la carpeta de imágenes (img) del proyecto.
Construyendo el sitio
Una vez terminada la documentación de un proyecto se puede construir el sitio web correspondiente ejecutando en la consola el siguiente comando:
$ mkdocs build
El proceso de construcción consiste en crear un directorio llamado site con todos los archivos del sitio, entre los que se incluyen los archivos HTML con la documentación creada en dicho formato. Todo el sitio podrá alojarse en un servidor web o en páginas de proyectos como GitHub y Amazon S3.
Para construir el sitio eliminando documentos obsoletos que han sido retirados de la documentación, ejecutar:
$ mkdocs build --clean
Para obtener información de ayuda de otras opciones disponibles:
$ mkdocs build --help
$ mkdocs build
El proceso de construcción consiste en crear un directorio llamado site con todos los archivos del sitio, entre los que se incluyen los archivos HTML con la documentación creada en dicho formato. Todo el sitio podrá alojarse en un servidor web o en páginas de proyectos como GitHub y Amazon S3.
Para construir el sitio eliminando documentos obsoletos que han sido retirados de la documentación, ejecutar:
$ mkdocs build --clean
Para obtener información de ayuda de otras opciones disponibles:
$ mkdocs build --help
Finalizamos esta introducción animándoles a visitar el sitio oficial para conocer el resto de opciones de configuración que tiene está fantástica herramienta y para profundizar en su conocimiento.
Ir al índice del tutorial de Python
