• Saltar a la navegación principal
  • Saltar al contenido principal
Geoinnova

Consultoría y Formación en SIG, Territorio y Medio Ambiente

  • Geoinnova
    • Quiénes somos
    • Coworking en Pamplona
    • Alianzas Estratégicas
    • Visor de proyectos Geoinnova
  • SIG y Desarrollo
    • Plugins QGIS
    • GeoNode
    • QElectricGIS
    • Planero Web
  • Consultoría Ambiental y Territorial
  • Formación
    • Todos los cursos
    • Formación para empresas
    • Máster y Diplomas
    • Cursos de QGIS Online Certificados
    • Cursos de programación, desarrollo SIG y geoservicios
    • Cursos de Teledetección
    • Cursos de Giswater
    • Cursos de SIG con ArcGIS
    • Cursos de Medio Ambiente
    • Campus
  • Divulgación
    • Blog
    • Tertulia Territorio Geoinnova
    • TFMs y otro trabajos de alumnos
    • Noticias
    • Webinars
    • Geolibrería
  • Contacto
    • Soporte – Tickets
CURSOS DE GISWATER APÚNTATE
Programación y Desarrollo SIG SIG Tecnología

MkDocs: Cómo crear y publicar documentación eficientemente

10/09/2024 Deja un comentario

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.

Contenidos ocultar
Requisitos Previos
Instalar MkDocs
Crear un Nuevo Proyecto
Servir el Proyecto en Desarrollo
Editar la Documentación
Configurar el Proyecto
Construir y Desplegar el Sitio Estático en GitHub Pages
Construir el Sitio Estático
Desplegar en GitHub Pages
Automatización del despliegue con cada commit

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 --version

Si 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.py

Instalar MkDocs

Para instalar MkDocs, abre tu terminal o línea de comandos y ejecuta:

pip install mkdocs

Verifica que MkDocs se haya instalado correctamente con la siguiente instrucción:

mkdocs --version

Crear un Nuevo Proyecto

Vamos a crear un nuevo proyecto de documentación llamado «user-guide«. Para iniciarlo ejecutaremos:

mkdocs new user-guide
cd user-guide

Esto 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.md

site_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 build

Este 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 init 
git remote add origin https://github.com/tu-usuario/user-guide.git 
git 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-pages como 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.

Apúntate a nuestra newsletter semanal

"*" señala los campos obligatorios

Este campo es un campo de validación y debe quedar sin cambios.
Consentimiento*

Artículos relacionados

SUDS-DSU-tanques-de-tormentas-gestión-drenaje-urbano-giswater-geoinnova
SUDS, DSU y tanques de tormentas: cómo se relacionan en la gestión del drenaje urbano
16/10/2026
cobertura-hidrantes-giswater-epanet-redes-abastecimiento-geoinnova
Cobertura de hidrantes en redes de abastecimiento: análisis espacial y comprobación hidráulica con Giswater
15/10/2026
giswater-qgis-epanet-swmm-gestion-redes-agua-geoinnova
¿Qué es Giswater y cómo se utiliza en la gestión de redes de abastecimiento y saneamiento?
15/10/2026

Eva Rabasco

Full Stack Developer. Comprometida con el diseño y desarrollo de materiales innovadores basados en la Web. Amplia experiencia en tecnologías específicas del lado cliente y del servidor.

Actualmente forma parte del equipo de Programación y Desarrollo SIG de la Asociación Geoinnova.

Además desarrolla su labor como docente en algunos de los cursos de bases de datos y de programación SIG del catálogo de cursos de Geoinnova.

Interacciones con los lectores

¿Quieres comentarnos algo? Adelante! Cancelar la respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Geoinnova
c/ Luis Morondo Urra nº 8 Bajo A
31006 Pamplona (Navarra)
info@geoinnova.org
+34 948 117 137

Horario de atención

Lunes a Viernes - 09:00 a 14:00.
Fines de semana y Festivos - Exclusivamente por mail.
Horario de Verano (01 de julio al 30 de agosto): De lunes a viernes de 8 a 15h.

Otras páginas de interes

  • Promociones y descuentos en formación
  • Formación bonificada FUNDAE
  • Verificador y descarga de Certificados de aprovechamiento
  • Cursos certificable por QGIS.org

Legal

  • Aviso Legal
  • Política de privacidad
  • Política de seguridad
  • Política de cookies
  • Términos y condiciones
Entidad adherida a Confianza Online Certificado de inscripción en el Registro de huella de carbono, compensación y proyectos de absorción Logo Plazox Certificado de conformidad con el ENS

Todo el contenido publicado desde 2009 hasta 2026 en el Blog de Geoinnova por Geoinnova y colaboradores está licenciado bajo CC BY-NC-ND 4.0
Para usos específicos, contactar con Geoinnova.

© 2026 · Desarrollada por Geoinnova

Gestionar el Consentimiento de las Cookies
Utilizamos tecnologías como las cookies para almacenar y/o acceder a la información del dispositivo. Lo hacemos para mejorar la experiencia de navegación y para mostrar anuncios personalizados. El consentimiento a estas tecnologías nos permitirá procesar datos como el comportamiento de navegación o las identificaciones únicas en este sitio. No consentir o retirar el consentimiento, puede afectar negativamente a ciertas características y funciones.
Funcional Siempre activo
El almacenamiento o acceso técnico es estrictamente necesario para el propósito legítimo de permitir el uso de un servicio específico explícitamente solicitado por el abonado o usuario, o con el único propósito de llevar a cabo la transmisión de una comunicación a través de una red de comunicaciones electrónicas.
Preferencias
El almacenamiento o acceso técnico es necesario para la finalidad legítima de almacenar preferencias no solicitadas por el abonado o usuario.
Estadísticas
El almacenamiento o acceso técnico que es utilizado exclusivamente con fines estadísticos. El almacenamiento o acceso técnico que es utilizado exclusivamente con fines estadísticos anónimos. Sin una requerimiento, el cumplimiento voluntario por parte de su proveedor de servicios de Internet, o los registros adicionales de un tercero, la información almacenada o recuperada sólo para este propósito no se puede utilizar para identificarlo.
Marketing
El almacenamiento o acceso técnico es necesario para crear perfiles de usuario para enviar publicidad, o para rastrear al usuario en un sitio web o en varios sitios web con fines de marketing similares.
  • Administrar opciones
  • Gestionar los servicios
  • Gestionar {vendor_count} proveedores
  • Leer más sobre estos propósitos
Personalizar
  • {title}
  • {title}
  • {title}