Instalación de MkDocs

En esta guía utilizaremos Linux

¿Qué es MkDocs?

MkDocs es una herramienta de código abierto que sirve para crear sitios web de documentación estáticos a partir de archivos en formato Markdown.

¿Cómo se instala MkDocs?

1. Requisitos previos.

Antes de empezar con la instalación debemos tener instalado:

• Python (versión 3.7 o superior)
• El gestor de paquetes pip
• Recomendable: Editor de código (en nuestro caso Visual Studio Code )

2. Instalación de Python .

Antes de instalar asegúrate de que NO lo tienes instalado porque normalmente ya viene instalado.

pyhton3 --version

Python 3.12.3

Sino, puedes instalarlo con el siguiente comando

sudo apt install python3

Detalles importantes:

• En Windows se usa python.
• En Mac//Linux normalmente python3.
• pip se instala junto con python en la mayoría de casos.

3. Instalación de pip.

Antes de instalar nos aseguramos de que NO está instalado

pip --version

Sino, instalamos nosotros con

sudo apt install python3-pip

4. Creamos un entorno virtual.

Para la instalación de MkDocs necesitamos un entorno donde crear nuestro proyecto, por eso son necesarios estos 2 pasos anteriores.

Abrimos la terminal y escribimos este comando para crear el entorno

python3 -m venv .venv

Puedes comprobar que ha surtido efecto si en la carpeta del proyecto donde estás situado aparece un directorio llamado ".venv"

Ahora activamos el entorno

source .venv/bin/activate

5. Instalación de MkDocs.

Utilizaremos pip para instalarlo

pip install mkdocs

Cuando esté instalado lanzamos el comando que nos creará todos los archivos necesarios para comenzar.

¡Recuerda! Dentro de la carpeta del proyecto

mkdocs new .

• mkdocs.yml
• docs/index.md

Ahora ya tenemos MkDocs pero no es lo único por hacer, hay muchos temas disponibles para mejorarlo significativamente, uno de ellos y el más usado es "material for mkdocs".

Pero como podemos instalarnos muchas cosas y podría ser un lío no saber ni que nos hemos intalado (además para llevar un orden) es muy importante incluir en nuestro proyecto un fichero de requirements.

6. Fichero requirementes.txt

Es un fichero de texto que se usa en proyectos Python para listar todas las dependencias (librerías) que necesita tu proyecto para funcionar.

Para implementarlo solo tenemos que crear el fichero

touch requirements.txt

e introducir algo como esto

1
2
3
4
5

mkdocs==1.6.1
mkdocs-get-deps==0.2.0
mkdocs-material==9.6.11
mkdocs-material-extensions==1.3.1
pymdown-extensions==10.14.3

Luego para activarlo escribiremos el siguiente comando.

pip install -r requirements.txt

¿Por qué es súper necesario?

1. Reproducibilidad

   Todos usan las mismas versiones, lo que evita errores tipo "en mi máquina no funciona"

2. Trabajo en equipo

   Cualquier persona puede levantar tu proyecto en segundos con:

   pip install -r requirements.txt
   

3. Despliegues (deploy)

   Plataformas como servidores o CI/CD necesitan saber qué instalar. Sin ese archivo, el proyecto puede fallar directamente.

4. Control de versiones

   Evitas incompatibilidades, evitas que algo deje de funcionar por actualizaciones

En nuestro caso en el archivo requirements.txt ya hemos añadido el materials for mkdocs por lo que no tendremos que instalarlo a mano. Podríamos hacerlo con este comando en caso de no tener este fichero

pip install mkdocs-material

7. Lanzar el MkDocs

Ya una vez tenemos todos los pasos anteriores y hemos comprendido como funciona, solo falta lanzar el proyecto.

Utilizaremos el puerto 8080 para evitar conflictos.

mkdocs serve -a localhost:8080

Añadir el 'livereload'

mkdocs serve --livereload

¿Qué es 'MkDocs Build'?

mkdocs build

Convierte archivos

• markdown (archivos)
• .yml (configuración)

en

• HTML
• CSS
• JS

es decir: una web completa estática.