Cómo colaborar

Documentar aquí debería costar lo mínimo: un archivo Markdown en la carpeta que toque y un push. La fecha y el autor se rellenan solos desde git, así que no hay que mantener frontmatter de metadatos.

Antes de escribir, lee la guía de estilo

Hay una guía de estilo para los artículos (GUIA-ESTILO-ARTICULOS.md, en la raíz del repositorio). Resume cómo escribimos: respuesta arriba (pirámide invertida), honestidad sobre los errores, evidencia en tablas, citas literales, definiciones inline, títulos descriptivos y qué admoniciones usar. Échale un vistazo antes de empezar un artículo nuevo.

Redactar con Claude a partir de un borrador

La guía de estilo (GUIA-ESTILO-ARTICULOS.md) está pensada para pegarse como contexto en Claude y que reescriba un borrador con el estilo de la base: la respuesta arriba (pirámide invertida), errores contados con honestidad, evidencia en tablas, citas literales, términos definidos inline, títulos descriptivos y las admoniciones de MkDocs Material que usamos.

Si ya tienes un artículo base (unas notas, un hilo de chat, un postmortem sin pulir), el flujo es:

Abre un chat con Claude y pega el contenido completo de GUIA-ESTILO-ARTICULOS.md como instrucciones.
A continuación pega tu artículo base y pídele que lo reescriba siguiendo la guía. Por ejemplo:

Reescribe el siguiente borrador siguiendo la guía de estilo que te acabo de dar: pirámide invertida, TL;DR arriba, evidencia en tablas y el cierre canónico (Qué nos llevamos + anexo). Este es el borrador: [...]

Revisa el resultado contra el checklist antes de publicar de la propia guía y ajusta lo que haga falta antes del push.

Publicar un artículo

Crea un archivo .md dentro de la carpeta de la categoría correspondiente, en docs/. Por ejemplo: docs/rag-y-retrieval/mi-articulo.md.
Empieza el contenido con un título de primer nivel (# Título del artículo). Ese título es el que aparece en la navegación y en "Últimos artículos".
(Opcional) Añade tags al principio del archivo para que el artículo aparezca en el índice de tags:

---
tags:
  - ollama
  - rag
---

Haz push. El pipeline regenera el site. La fecha del último cambio y tu nombre como autor salen automáticamente del commit.

No hace falta editar mkdocs.yml ni ningún índice: la navegación se construye sola a partir de las carpetas.

Enlazar a otros documentos

Usa enlaces Markdown normales, pero apuntando al archivo .md (no a la URL final). MkDocs los reescribe solos y, además, avisa en el build si el enlace está roto o si mueves el archivo. La ruta es relativa al documento desde el que escribes.

<!-- a otro artículo de la MISMA carpeta -->
Ver también [quién sintetiza el RAG](quien-sintetiza-rag.md).

<!-- a un artículo de OTRA carpeta: subes con ../ -->
Relacionado con [contexto perdido en Gemma](../infraestructura-local/contexto-perdido-role-tool.md).

<!-- a la portada de una sección (su index.md) -->
Más en [RAG y retrieval](../rag-y-retrieval/index.md).

<!-- a una sección concreta dentro de un artículo (ancla) -->
Como expliqué en el [TL;DR](hybrid-search-multilingue.md#tldr).

Las anclas (#...) se generan automáticamente a partir de los títulos: en minúsculas, con los espacios convertidos en guiones y sin acentos ni símbolos. Así ## TL;DR se convierte en #tldr y ## Causa raíz en #causa-raiz.

Dos reglas: apunta siempre al .md y nunca uses enlaces absolutos tipo /rag-y-retrieval/... (esos no los valida MkDocs y se rompen al desplegar bajo un subdirectorio). Si al construir ves un WARNING de "unrecognized relative link", es que la ruta no apunta a un archivo existente.

Imágenes y gráficos

Las imágenes (diagramas, gráficos, capturas) no van junto al .md: se guardan todas en docs/assets/images/. Desde un artículo, que vive en la carpeta de su categoría, las referencias con ruta relativa subiendo un nivel:

![Texto alternativo que describe la imagen](../assets/images/mi-grafico.svg)

Cuatro reglas:

Ubicación: siempre en docs/assets/images/, nunca sueltas en la carpeta del artículo.
Nombre descriptivo en kebab-case; si la imagen refleja datos de un momento concreto, añade la fecha (coste-total-2026-06.svg).
Formato: prefiere SVG para diagramas y gráficos (nítidos a cualquier zoom, ligeros y editables); PNG solo para capturas de pantalla.
Texto alternativo siempre: el ![...] describe qué muestra la imagen, no la repitas como pie.

Formato enriquecido: avisos, pestañas y código

Material añade tres bloques muy útiles para los artículos. En los tres, la regla de oro es la misma: el contenido va indentado 4 espacios respecto a la línea que lo abre. Es, de lejos, el error más habitual.

Avisos (admoniciones)

Cajas con color e icono para destacar notas, avisos o ejemplos. !!! crea una caja fija; ??? una plegable (empieza cerrada) y ???+ una plegable que empieza abierta. El título entre comillas es opcional.

!!! note "Título opcional"
    Contenido de la caja, indentado 4 espacios.

??? warning "Detalles que ocupan"
    Empieza plegada; el lector la despliega si le interesa.

Tipos disponibles: note, tip, info, warning, danger, success, question, example, quote.

Pestañas de contenido

Varios bloques que el lector alterna con pestañas mostradas en la misma fila. Cada pestaña es === "Título". Para que se agrupen en una sola barra de pestañas: los bloques van seguidos (solo una línea en blanco entre ellos) y todo su contenido va indentado 4 espacios, incluidas las líneas ``` de los bloques de código.

=== "Python"

    ```python
    print("hola")
    ```

=== "Bash"

    ```bash
    echo hola
    ```

Eso produce una sola barra: Python | Bash. Si te salen apiladas en vez de en fila, casi siempre es porque las líneas ``` del código no están indentadas 4 espacios, o porque hay texto (un título, una imagen) entre una pestaña y la siguiente que rompe el grupo.

Mejoras en bloques de código

Opciones que se escriben en la misma línea de apertura del bloque, después del lenguaje:

```python title="agente.py" hl_lines="2 4-6" linenums="1"
def run():
    config = load()
    paso_uno()
    paso_dos()
    paso_tres()
```

title="archivo.py" — añade una cabecera con el nombre del archivo.
hl_lines="2 4-6" — resalta líneas concretas; admite rangos como 4-6.
linenums="1" — numera las líneas empezando por el número indicado.

Categorías

Cada categoría es una carpeta en docs/:

Infraestructura local — infraestructura-local/
Hardware y modelos — hardware-y-modelos/
RAG y retrieval — rag-y-retrieval/
Diseño de agentes — diseno-agentes/
Medición y experimentos — medicion-y-experimentos/
Trucos para usar Claude — trucos-claude/

¿Necesitas una categoría nueva? Crea una carpeta con un index.md que la describa y un archivo .pages con title: Nombre bonito. Aparecerá sola en el menú.

Categorías son temas, no proyectos

Las carpetas del primer nivel son temas (RAG, agentes, infraestructura…). Un proyecto —Mentat, recommender, el cliente de turno— no lleva carpeta propia: se marca con un tag y su artículo vive en el tema que le corresponda.

El motivo es que un artículo suele ser las dos cosas a la vez: "Seguridad por escenario de despliegue en Mentat" es infraestructura y es Mentat. Una carpeta te obliga a elegir una; un tag no, y además agrupa los artículos del proyecto desde el primero que escribes.

Si un proyecto acumula 4-5 artículos o más, entonces sí merece una subcarpeta dentro de su tema (p. ej. infraestructura-local/mentat/), nunca una categoría en el primer nivel: si los proyectos suben al primer nivel, compiten con los temas y el menú deja de tener un criterio único.

Actualizar un artículo ya publicado

Cuando cambias un artículo que ya llevaba tiempo publicado, en los listados de "Últimos artículos" aparece con la etiqueta Actualizado y su fecha de publicación original, no la del cambio. Así quien ya lo había leído entiende que hay algo nuevo dentro, en vez de creer que se ha publicado dos veces.

Se decide solo, a partir de git, y hace falta que se cumpla todo esto:

Que el cambio llegue más de 14 días después de publicar. Retocar un artículo recién salido es parte de escribirlo, así que sigue contando como novedad.
Que toque al menos 15 líneas. Arreglar enlaces o mover el fichero de carpeta no marca nada.
Que el asunto del commit no lleve [menor].

Ese [menor] es el escape manual: si corriges una errata en un artículo antiguo y no quieres que suba a los listados como actualizado, ponlo en el mensaje del commit.

git commit -m "Corrige la cifra de latencia del rerank [menor]"

Al revés, si el cambio importa —una corrección de fondo, una sección nueva, un veredicto que se invalida— no pongas nada y deja que se etiquete. Y si lo que has cambiado deja obsoleta una parte del artículo, dilo dentro con una admonición fechada, no solo en el commit: el lector que llega desde Google no ve el historial de git.

El criterio vive en hooks/article_dates.py por si hay que ajustar esos números.

Sobre la autoría

El nombre que aparece en cada artículo —y en la página de Autores— es el del autor de los commits según git. No se escribe a mano en ningún sitio: sale solo del historial.

Por eso, lo único imprescindible es que configures tu identidad de git la primera vez que clonas el repo (si no, tus artículos saldrían sin nombre o con uno incorrecto):

git config user.name "Nombre Apellido"
git config user.email "nombre@asmtch.com"

Usa git config --global ... si quieres que valga para todos tus repos. Puedes comprobar que está bien con git config user.name y git config user.email.

La atribución es por líneas (estilo git blame): si escribes un artículo y otra persona corrige una errata, aparecéis los dos, pero tú como autor principal. Para ver quién hizo qué sin construir el site: git log -- docs/ruta/al-articulo.md o git shortlog -sne -- docs/.