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 muy sencillo.
Instalamos Git en nuestro ordenador
¿Pasos previos? 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 crear, 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és tu proyecto de MkDocs.
Conectamos nuestro proyecto local con el repositorio online
Mediante HTTPS (con tu clave). Puedes hacerlo directamente:
echo "# algoentremanos" >> README.md
git init
git config user.name "Tu nombre"
git config user.email "tu email"
git add .
git commit -m "first commit"
git branch -M main
git remote add origin [email protected]:tu_usuario/tu_repositorio.git
git push -u origin mainMediante SSH (con una clave SSH que hay que crear). Tienes que pasar antes al paso siguiente:
echo "# algoentremanos" >> README.md
git init
git config user.name "Tu nombre"
git config user.email "tu email"
git add .
git commit -m "first commit"
git branch -M main
git remote add origin [email protected]: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 [email protected]En 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 main¿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.
