Tutorial compacto de MkDocs¶

Convierte tu carpeta de Markdown en un sitio HTML moderno con buscador.

1) Instalación (Ubuntu 24.04 con entorno virtual)¶

# 1) Dependencias del sistema (si no tienes venv)
sudo apt update && sudo apt install -y python3-venv

# 2) Crear y activar entorno virtual en el proyecto
python3 -m venv .venv
source .venv/bin/activate

# 3) Instalar MkDocs y tema Material dentro del venv
pip install --upgrade pip
pip install mkdocs mkdocs-material

# 4) (Opcional) Salir del venv cuando acabes
# deactivate

Sugerencia: añade .venv/ a tu .gitignore.

2) Crear proyecto base¶

mkdocs new mi-sitio
cd mi-sitio

Estructura inicial:

mi-sitio/
  mkdocs.yml        # configuración
  docs/
    index.md        # portada

3) Traer tu contenido¶

Copia tu árbol de .md dentro de docs/ respetando subcarpetas:

docs/
  index.md
  guia/
    intro.md
    avanzado.md
  referencias/
    api.md

4) Configuración mínima (`mkdocs.yml`)¶

site_name: Mi Documentación
theme:
  name: material     # o "readthedocs" si no instalas material
nav:                 # navegación manual (opcional, recomendado)
  - Inicio: index.md
  - Guía:
      - Introducción: guia/intro.md
      - Avanzado: guia/avanzado.md
  - Referencias:
      - API: referencias/api.md

Notas:

Si omites nav, MkDocs genera navegación simple por archivos.
Para salida en otra carpeta, añade:

site_dir: ../salida_html

5) Vista previa y build¶

mkdocs serve   # http://127.0.0.1:8000 con recarga en caliente
mkdocs build   # genera HTML en site/ (o en site_dir si lo definiste)

6) Mejoras rápidas (Material)¶

En mkdocs.yml:

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest
    - content.code.copy
markdown_extensions:
  - admonition
  - toc:
      permalink: true
  - footnotes
  - tables
  - codehilite
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/tuusuario

Bloques de admonición en tus .md:

!!! note "Recuerda"
    Este es un bloque de nota.

6.1) Resaltar líneas en bloques de código¶

Plugin/extensión recomendada: pymdownx.highlight (y pymdownx.superfences).

Instala dependencias en tu entorno virtual:

pip install pymdown-extensions pygments

Activa en mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true   # anclas por línea (útil para enlazar)
      linenums: null         # SIN números de línea por defecto
      linenums_style: table   # (solo si algún bloque los activa)
      pygments_lang_class: true

Con linenums: false los bloques no mostrarán números de línea salvo que se pidan explícitamente.

Control por bloque (cuando necesites numeración):

```python linenums="3" hl_lines="1 3"
# Este bloque SÍ tendrá números, empezando en 1
print("a")
print("b")
```

# Este bloque SÍ tendrá números, empezando en 3 
print("a")
print("b")

¿Ya tienes números globales y quieres ocultarlos?
Opción A (recomendada): pon linenums: false en pymdownx.highlight y usa linenums="1" solo donde quieras numeración.
Opción B (rápida sin tocar YAML): añade CSS para ocultarlos visualmente.

CSS para ocultar numeración (Material):

Crea docs/styles/ocultar-linenums.css con:

/* Oculta columna de números y ajusta ancho del código */
.md-typeset .highlighttable .linenos, 
.md-typeset .highlighttable .linenodiv { display: none; }
.md-typeset .highlighttable td.code { width: 100%; }

Declara en mkdocs.yml:

extra_css:
  - styles/ocultar-linenums.css

Con Material for MkDocs, pymdownx.highlight ofrece mejor integración visual que codehilite puro.

7) Enlaces, imágenes y estáticos¶

Enlaces internos: rutas relativas dentro de docs/ (p. ej. [Avanzado](../guia/avanzado.md) o sin extensión [Avanzado](../guia/avanzado/)).
Imágenes: colócalas en docs/img/ y enlaza ![Alt](img/diagrama.png).
Archivos estáticos (PDF, etc.): también bajo docs/.

8) Búsqueda¶

MkDocs incluye buscador por defecto. Con Material ya viene listo; no hay que configurar nada extra.

9) Despliegue¶

GitHub Pages (rápido)¶

pip install mkdocs-material  # en CI/entorno de build
mkdocs gh-deploy --force     # crea rama gh-pages y publica

O configura un workflow que ejecute mkdocs build y publique site/.

Servidor propio¶

Sirve el contenido estático de site/ (o site_dir) con Nginx/Apache o cualquier hosting estático (Netlify, Cloudflare Pages, Vercel).

10) Opcional: versionado de docs¶

Para docs versionadas (v1, v2, etc.) usa mike:

pip install mike
mike deploy 1.0
mike set-default 1.0

11) Problemas comunes (y soluciones)¶

404 al navegar: revisa que el nav apunte a rutas correctas bajo docs/.
Enlaces rotos tras build: evita enlaces absolutos a disco; usa relativos desde el archivo actual.
CSS no aplicado: confirma theme.name correcto y que instalaste el paquete del tema.
Salida en el mismo repo: usa site_dir para poner los HTML en otra carpeta de salida.