MkDocs es una solución integral para crear y publicar documentación de proyectos de manera eficiente. Se basa en Markdown, facilitando el uso y mantenimiento, y utiliza YAML para configurar el sitio de documentación de manera sencilla.

¿Para Qué Sirve MkDocs?
- Documentar Proyectos de Software: especialmente para proyectos de código abierto y software, donde una documentación clara y accesible es esencial para el uso y la colaboración.
- Crear Manuales de Usuario: Perfecto para elaborar guías y manuales detallados para productos o servicios, mejorando la experiencia del usuario.
- Generar Documentación Interna: Útil para desarrollar documentación interna para equipos de desarrollo, operaciones y otros departamentos dentro de una organización, facilitando la comunicación y el conocimiento compartido.
En este artículo, te explicaremos los pasos para instalar MarkDoc, realizar algunos ajustes esenciales y añadir contenido, además de cómo automatizar la publicación de tu documentación cada vez que realices un commit en tu repositorio.
Requisitos Previos
Antes de empezar, asegúrate de tener Python y pip instalados en tu sistema. Puedes verificar si los tienes instalados ejecutando:
python --version
pip --versionSi no los tienes instalados, puedes descargarlos desde la página oficial de Phyton.
Las últimas versiones de Python instalan por defecto pip, sin embargo, si necesitas instalar pip por primera vez, descarga get-pip.py y ejecuta el siguiente comando para instalarlo:
python get-pip.pyInstalar MkDocs
Para instalar MkDocs, abre tu terminal o línea de comandos y ejecuta:
pip install mkdocsVerifica que MkDocs se haya instalado correctamente con la siguiente instrucción:
mkdocs --versionCrear un Nuevo Proyecto
Vamos a crear un nuevo proyecto de documentación llamado «user-guide«. Para iniciarlo ejecutaremos:
mkdocs new user-guide
cd user-guideEsto creará un nuevo directorio llamado `user-guide` con la estructura básica de un proyecto de MkDocs.

Servir el Proyecto en Desarrollo
Para ver tu proyecto en desarrollo en tiempo real, abre Visual Studio Code, inicia una terminal y ejecuta mkdocs serve.
mkdocs serve
Esto iniciará un servidor local y podrás ver tu documentación en el navegador web en http://127.0.0.1:8000/

Editar la Documentación
Edita el archivo `docs/index.md` para actualizar el contenido de la página principal de tu documentación. Usaremos Markdown para darle formato al texto.
Este sería un ejemplo de cómo podrías estructurar el contenido:
# Guía de Usuario
## Sección 1: Instalación
Pasos necesarios para instalar y configurar el proyecto.
### Requisitos Previos
- Requisito 1
- Requisito 2
### Pasos de Instalación
1. Paso 1: Descripción.
2. Paso 2: Descripción.
## Sección 2: Uso
Guía sobre cómo utilizar el proyecto después de instalarlo.
### Funcionalidad Principal
Cómo usar la funcionalidad principal.
### Casos de Uso
Ejemplos de casos de uso comunes.
## Sección 3: Contacto
Para más información o ayuda, contacta a través de:
- **Correo Electrónico:** [email@example.com](mailto:email@example.com)
- **GitHub:** [Repositorio del Proyecto](https://github.com/usuario/proyecto)

Configurar el Proyecto
Ahora podemos modificar aspectos de la configuración del proyecto para personalizar la documentación generada. Uno de los cambios más comunes es actualizar el título, que por defecto aparece como «My Docs». Vamos a cambiarlo y agregar una navegación básica que se verá reflejada en la barra superior:
site_name: Guía de usuario APP
nav:
- Inicio: index.md
- Sobre Nosotros: about.mdsite_name: Este es el título que aparecerá en la barra de navegación superior de la documentación. Cámbialo a «Guía de usuario APP» o el nombre que prefieras.
nav: Esta sección define la estructura de navegación de tu documentación.
- Inicio: Apunta al archivo
index.md, que es la página principal de tu documentación. - About: Apunta al archivo
about.md, que podría contener información adicional sobre el proyecto.

Construir y Desplegar el Sitio Estático en GitHub Pages
Para desplegar la documentación en GitHub Pages (un servicio gratuito de hosting para sitios web estáticos directamente desde un repositorio de GitHub), podemos seguir los siguientes pasos:
Construir el Sitio Estático
Ejecuta el siguiente comando para construir todos los archivos necesarios para tu sitio web estático, que se guardarán en la carpeta site:
mkdocs buildEste comando genera una versión estática de tu sitio, lista para ser desplegada en GitHub Pages u otro servidor web.
Desplegar en GitHub Pages
Para desplegar los archivos estáticos en GitHub Pages desde un repositorio de GitHub, seguiremos estos pasos:
- Crear un Repositorio en GitHub si aún no tienes uno.
- Configurar GitHub Pages
- Inicializar Git y Añadir los Archivos a tu repositorio.
- Desplegar los en GitHub Pages
Crear un Repositorio en GitHub
Accede a GitHub, haz clic en New repository, ingresa el nombre de tu proyecto (en nuestro caso le pondremos el mismo nombre user-guide), configura la visibilidad y haz clic en Create repository.

Inicializar Git y añadir los Archivos a tu repositorio.
git initgit remote add origin https://github.com/tu-usuario/user-guide.gitgit add .git commit -m "Initial commit"
Configurar GitHub Pages
Asegúrate de que GitHub Pages esté configurado para usar la rama gh-pages. Esta configuración es necesaria para que tu sitio web esté disponible en una URL pública. Para ello:
- Navega a la pestaña Settings (Configuración).
- En el menú de la izquierda, selecciona Pages.
- En Source (Fuente), selecciona
gh-pagescomo la rama y la carpeta raíz. - Guarda los cambios.

Desplegar en GitHub Pages
Usa el siguiente comando para desplegar tu sitio:
mkdocs gh-deploy
Este comando construirá tu sitio y lo subirá a la rama gh-pages de tu repositorio de GitHub, haciendo que tu documentación esté disponible en https://tu-usuario.github.io/user-guide.

Con estos pasos, tu documentación estará desplegada y accesible en GitHub Pages.
*Cada vez que desees actualizar tu sitio en GitHub Pages con nuevos cambios, debes ejecutar mkdocs gh-deploy manualmente. Esto asegura que los cambios en tu documentación local se reflejen en el sitio web desplegado.
Automatización del despliegue con cada commit
Si deseas que tu sitio se actualice automáticamente con cada commit, puedes usar GitHub Actions para integrar el proceso en una pipeline de CI/CD. Consulta nuestra entrada detallada sobre «GitHub Actions: Automatizando el Despliegue de una Aplicación React» para obtener instrucciones completas sobre cómo configurarlo.
No obstante, a continuación, te proporcionamos un archivo de ejemplo para ayudarte a comenzar:
name: Deploy Documentation
on:
push:
branches:
- main # O la rama que desees usar
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.x'
- name: Install MkDocs and GitHub Pages
run: |
pip install mkdocs mkdocs-material ghp-import
- name: Build and deploy
run: |
mkdocs build
ghp-import -n -p -b gh-pages site
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Esta configuración garantiza que tu sitio en GitHub Pages se mantenga siempre actualizado con los últimos cambios en tu documentación, ya que desplegará automáticamente el sitio cada vez que realices un push a la rama main.
¡Y eso es todo! Ahora tienes una documentación básica en MkDocs lista para ser visualizada y desplegada.
¿Quieres comentarnos algo? Adelante!