Si eres un desarrollador de software profesional que busca una plataforma para crear documentación elegante para uno de tus proyectos, o alguien que trabaja en una empresa que necesita crear una documentación interna para el personal, o incluso solo un usuario avanzado que quiere guardar algunas notas en una buena manera, MkDocs es la mejor herramienta para ti.
MkDocs es un generador de sitios estáticos que está orientado a la creación de plataformas de documentación. Es bastante simple, atractivo y fácil de configurar e implementar. Escrito en Python, simplemente requiere que crees tus archivos en formato Markdown, y luego, simplemente usando un único archivo de configuración YAML, puede generar un sitio web estático funcional para ti.
Configuración inicial
Configurar MkDocs es bastante simple. Puedes instalarlo fácilmente usando pip:
$ pip install mkdocs
Luego, en tu directorio de trabajo, ejecuta el siguiente comando para inicializar un sitio:
$ mkdocs new mkdocsproject
Y luego para comenzar a servirlo:
$ cd mkdocsproject mkdocs serve
A continuación, puedes ir a localhost:8000 (o tu dirección IP/nombre de host con el puerto 8000) para ver cómo funcionan los MkDocs.
Despliegue y personalización
En la carpeta mkdocsproject, verás la siguiente estructura:
mkdocsproject/mkdocs.yml: el archivo de configuración para MkDocs.
mkdocsproject/docs: aquí es donde se colocan tus archivos para que se atiendan. Asegúrate de tener un archivo llamado index.md (que será la página principal). Puedes tener páginas en subdirectorios como acerca/ cualquiercosa.md.
mkdocsproject/site: aquí es donde MkDocs generará los archivos HTML. No hagas modificaciones aquí.
mkdocsproject/mkdocs: un pequeño directorio para los activos de MkDocs (como la funcionalidad de búsqueda).
Como MkDocs es un generador de sitios estáticos que solo generará archivos estáticos (no se necesita un motor back-end como PHP o Python), puedes 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 example.com; root /var/www/mkdocsproject/site; index index.html; location / {
try_files $uri $uri/ =404;
}
}
Reemplaza example.com con el dominio que tienes en tu servidor, y también /var/www/mkdocsproject/site con la ruta de la subcarpeta del sitio en tu servidor. Y reinicia nginx:
$ sudo service nginx restart
Ahora puedes dirigirte a example.com y verlo funcionar.
El tema predeterminado de MkDocs no es tan bueno. ¡Pero también puedes instalar decenas de otros temas en un minuto! Recomendamos el tema Materia que es un tema fantástico adecuado para la mayoría de los sitios de documentación:
$ pip install mkdocs-material
Luego, para activar el tema, tendrás que editar tu archivo mkdocs.yml y hacerlo similar de esta manera (se agregan algunas opciones adicionales):
site_name: My MkDocs Project
site_url: 'http://example.com'
repo_url: 'https://github.com/username/projecturlongithub'
edit_uri: edit/master
site_description: 'A simple desc here.'
google_analytics: ['UA-xxxxxxxxx-x', 'example.com']
extra:
favicon: 'https://example/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: 'mydisqusname'
theme:
name: 'material'
Las opciones son bastante sencillas, pero aquí hay algunas explicaciones:
repo_url: es tu URL del repositorio de Git. Si planeas integrar una rama de 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 directamente desde su proyecto de MkDocs.
edit_uri: este es el postfijo para editar páginas, en GitHub, es edit/master. Puedes cambiar si estás usando GitLab o GitBucket.
google_analytics: no hay panel de control para MkDocs. Entonces, para saber quién visita tu sitio web, deberás usar Google Analytics. Esta opción te permite insertar tu número de seguimiento para asociar tu cuenta con tu sitio web.
disqus: si deseas habilitar el sistema de comentarios Disqus en tu sitio web, puedes insertar tu nombre corto aquí.
tema: el nombre del tema que deseas usar.
Luego ejecuta la compilación de mkdocs dentro de la carpeta mkdocsproject, y tu sitio web tendrá el aspecto y la apariencia predeterminados del tema Materia:
Hay muchos otros temas y opciones para configurar tu sitio web. Puedes consultarlos desde la documentación oficial de MkDocs. Aquí hay una lista de opciones posibles de MkDocs.
Importante: asegúrate de ejecutar la compilación de mkdocs siempre después de cada modificación que hagas a los archivos de MkDocs; de lo contrario, no verás ningún cambio.
Ejemplo de caso de uso: notas de FOSS
FOSS Notes es una plataforma de colaboración en línea para compartir notas, sugerencias y soluciones relacionadas con el software de código abierto. Hemos estado usando MkDocs durante más de un año.
Nuestra configuración depende principalmente del repositorio de GitHub. Cualquiera puede bifurcar las notas, agregar tus propias notas y luego enviarnos una solicitud de extracción para que nos fusionemos. Después de eso, cada hora, hay un pequeño script bash ejecutándose en nuestro servidor que ejecuta una sincronización entre el repositorio GitHub y la implementación web.
Aquí está nuestro pequeño guión:
#!/bin/bash
cd /var/www/fossnotes
rm -rf olddocs
mv docs olddocs
git clone https://github.com/foss-project/fossnotes/ docs
cp posts-cover.svg docs/posts-cover.svg
cd docs
mv README.md index.md
for d in */ ; do
cd $d
for file in *.md
do
tmpr=${file::-3}
filename=$(printf "%s" "$tmpr" | tr '[:lower:]' '[:upper:]')
cp ../posts-cover.svg $filename.oldsvg
sed "s/DUMMY TEXT/$filename/g" $filename.oldsvg > $filename.svg
convert $filename.svg $filename.png
rm $filename.oldsvg $filename.svg
s=""
sed -i '/^#[^#]/a \'"$s" $file
done
cd ..
done
mkdocs build
No es el mejor Bash que puedes obtener, pero cumple su función:
Ve al directorio de trabajo y elimina la carpeta olddocs. Y luego mueve la carpeta docs (que contiene la copia anterior de la documentación) a la carpeta olddocs.
Clona el repositorio de GitHub en la carpeta de documentos.
Ejecuta un bucle para que lea cada archivo de Markdown y tome el título del documento en una cadena, luego usa una plantilla SVG que tengamos, crea una imagen destacada para el documento (simplemente reemplazando el texto ficticio por el título) y pónlo en la misma carpeta del archivo Markdown, y luego insértarlo en el documento.
Reconstruye el proyecto MkDocs.
Poner esto en /etc/cron.hourly/ nos facilitará mucho la vida en lugar de hacerlo manualmente.
Conclusión
Puedes ver lo fácil que fue obtener un sitio web completo de documentación de trabajo utilizando MkDocs en cuestión de pocas horas. Hay muchos otros generadores de sitios estáticos similares, pero MkDocs los supera con la facilidad de configuración e implementación, y sencillez que proporciona para cualquier tipo de uso.
Un usuario normal también podría usar MkDocs para crear una plataforma de toma de notas local para él o cualquier otra cosa similar.
