Ya te he contado cómo montar tu web estática de manera sencilla con MkDocs, pero ahora vamos un paso más allá: vamos a conectar esa web, tus documentos .md con un repositorio de GitHub para llevar un control de cambios de tu documentación. Es sencillo.
Con ello vas a conseguir algo muy importante: que si tienes problemas con tu documentación o web creada en MkDocs, siempre podrás ir a GitHub y recuperar los cambios realizados y volver a una versión anterior. Es como una especie de backup gratuito.
Requisitos previos
Instalamos Git en nuestro ordenador
Tienes que tener instalado Git en tu ordenador. En macOS lo he instalado gracias a homebrew:
brew install gitPero en Windows o Linux puedes hacerlo también de manera sencilla: En Windows descargas la última versión desde aquí y la instalas. En Linux puedes usar apt-get install git (Ubuntu y Debian) o dnf install git (Fedora).
Creamos un repositorio en GitHub para nuestro proyecto
Una vez instalado Git en tu ordenador, solo tienes que ir hasta la carpeta donde tengas instalado tu proyecto de MkDocs e iniciar tu proyecto Git en local. ¡Ojo! Date de alta en GitHub y crea tu primer repositorio en https://github.com/new. Ponle el nombre que quieras y luego decide si quieres hacerlo público o privado. Empieza con Privado si estás montando tu proyecto.
En cuanto le das a generar, te va a salir la siguiente pantalla con todas las opciones que tienes que poner en el terminal de tu ordenador para conectarte a este repositorio online y subir tu web a GitHub.
Solamente tienes que poner estas instalaciones en orden para que funcionen y se conecten. Puedes elegir entre conectarte mediante HTTPS o mediante SSH (si tienes configuradas las claves SSH en tu ordenador y en GitHub). Todas estas órdenes hay que ejecutarlas desde la línea de comandos en la carpeta donde esté tu proyecto de MkDocs.
PASO 1: Inicializar Git en tu proyecto MkDocs
Antes de conectar tu documentación con GitHub, lo primero es activar el control de versiones dentro de la carpeta de tu proyecto MkDocs.
Abre tu terminal y navega hasta donde tienes creada tu web con MkDocs. Por ejemplo: cd ~/documentos/mi-documentacion-mkdocs.
En esa carpeta ejecuta:
git initEste comando crea una carpeta oculta llamada .git dentro de tu proyecto. Ahí Git guardará todo el historial de cambios.
Git necesita saber quién eres para asociar cada cambio a una persona. Pon exactamente el mismo nombre y email que usas en GitHub:
git config user.name "Tu Nombre"
git config user.email "tu-email@ejemplo.com"Tu proyecto MkDocs ya tiene archivos como mkdocs.yml y una carpeta docs/ con tus documentos .md. Añadelos todos a Git:
git add .
git commit -m "Versión inicial de la documentación con MkDocs"Paso 2: Crear repositorio en GitHub y conectarlo
Mediante HTTPS (con tu clave, recomendado para empezar).
Puedes hacerlo directamente:
echo "# Mi documentación con MkDocs" >> README.md
git branch -M main
git remote add origin https://github.com/tu_usuario/tu_repositorio.git
git push -u origin main- Nota: Ya ejecutaste: git init, git add . y git commit en el Paso 1. Por eso aquí solo conectamos y subimos.
Mediante SSH (con una clave SSH que hay que crear, para usuarios avanzados).
Tienes que pasar antes al paso siguiente:
git remote add origin git@github.com:tu_usuario/tu_repositorio.git
git push -u origin mainEn los dos casos vas a tener que autenticarte. Te recomiendo que des de alta las claves SSH en GitHub pinchando en la foto de tu perfil arriba a la derecha > Settings > SSH ang GPG Keys:
En esa Key en GitHub tienes que poner la clave pública de la SSH Key que hayas creado en tu ordenador, tal y como indican en https://docs.github.com/es/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account. ¿Cómo la generas en tu ordenador? Yo lo he hecho con 1Password, pero puedes hacerlo desde la línea de comandos: https://docs.github.com/es/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent y poner la clave privada con contraseña en tu agente SSH.
Para probar la conexión, puedes poner el siguiente comando en tu ordenador:
ssh -T git@github.comEn cuanto termines de poner git push -u origin main, todos los documentos de tu proyecto MkDocs se subirán a tu nuevo repositorio de GitHub. Así de sencillo.
Cuando vayas a hacer cambios en tu documentación local, puedes poner lo siguiente para que se suban online a GitHub:
git status
git add .
git commit -m "Actualización en la documentación de MkDocs"
git push origin mainPaso extra: Plugins para mostrar fechas y autores (con MkDocs Material)
¿Qué podemos añadir a Mkdocs para que tenga en cuenta nuestro repositorio de GitHub en su plantilla (con el tema Material)? Estos dos plugins, para que aparezcan la persona que ha creado la documentación y cuándo se han subido los documentos y los últimos cambios (https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/).
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-git-authors-pluginY en el tema de tu web con Material, te aparecerá algo así:
¡Ojo! Si quieres publicar tu web MkDocs con Material en las páginas gratuitas de GitHub, puedes hacerlo con GitHub Actions. Está todo explicado en https://squidfunk.github.io/mkdocs-material/publishing-your-site/. Yo no lo he hecho, porque las publico en mi propio servidor. Hay guías para hacerlo en Cloudflare, Netlify y muchos otros sitios. Las oportunidades son infinitas.
Github, Obsidian y MkDocs
¿Estás usando como yo Obsidian para gestionar la documentación de MkDocs? Pues entonces puedes instalar el plugin Obsidian Git, para gestionar las subidas de documentación y sincronización desde la interfaz de Obsidian. Si ya has realizado los pasos anteriores, la instalación de este plugin y puesta en marcha es sencilla.
Desde la barra derecha de Obsidian, vas a poder sincronizar toda tu documentación. Es muy cómodo.
¿Qué opciones estás usando tú? Me gustaría saberlo.
