Cómo publicar documentación desde Markdown

La documentación envejece bien en Markdown: es fácil de escribir, fácil de revisar y fácil de mantener junto a lo que documenta. Esta guía publica un conjunto de archivos Markdown como una página de documentación con secciones, usando Sentilis Press.

Una entrada, varias páginas

En Sentilis, un conjunto de documentación es una carpeta con un index.md. El index.md es la página principal; cada otro archivo .md junto a él se convierte en una sección:

press/
└── guia-de-la-api/
    ├── index.md              ← resumen (página principal)
    ├── autenticacion.md      ← sección
    ├── errores.md            ← sección
    └── attachments/
        ├── cover.png
        └── flujo.png

Las secciones tienen un solo nivel de profundidad: no hay secciones de secciones. Para una documentación más grande, publica varias entradas — una por tema — y enlázalas entre sí con sus URL completas.

Escribe la página principal

---
name: Guía de la API
category: Documentación
tags: api, referencia
---

# Guía de la API

Todo lo que necesitas para hacer tu primera petición.

- [Autenticación](./autenticacion.md)
- [Errores](./errores.md)

Los enlaces entre páginas de una misma entrada usan el nombre del archivo, como arriba. Los enlaces a cualquier otra cosa usan una dirección https:// completa.

Las secciones heredan la visibilidad

Las secciones toman status, visibility y password del index.md, así que una documentación privada no se filtra por una de sus páginas. Define esos campos en una sección para sobrescribirlos. Todo lo demás — category, tags — se define por página.

Imágenes y diagramas

Cada imagen local vive en la carpeta attachments/ de la entrada, con subcarpetas permitidas. Enlaza imágenes desde cualquier página de la entrada:

![Flujo de la petición](./attachments/flujo.png "Cómo se autentica una petición")

Un cover.png en attachments/ se usa al compartir la documentación. Todos los medios de la entrada, secciones incluidas, deben sumar 5 MB o menos.

Publica y mantenla al día

sentilis sync ./my-content

Actualiza una página, vuelve a sincronizar y la entrada se actualiza en su lugar. Guardar la documentación en Git hace que cada cambio se pueda revisar — mira docs as code para publicar en cada merge.

Consejos para una documentación que siga siendo útil

• Empieza por la tarea. El resumen debe decir qué puede hacer el lector después de leer.
• Un tema por sección. Las secciones cortas son más fáciles de enlazar y de mantener correctas.
• No pongas fecha a lo que no mantienes. Prefiere explicaciones estables a frases del tipo “a día de hoy”.

Publica tu documentación en Markdown →