Documentación Markdown con Mermaid
Documentación Markdown con Mermaid: guía práctica con demo copiable, checklist de revisión y notas de publicación para Markdown con Mermaid incrustado.
El problema real que resuelve
Documentación Markdown con Mermaid sirve cuando el diagrama no es solo una imagen, sino una pieza mantenible de documentación. La fuente debe seguir siendo legible, la vista previa debe detectar errores y la exportación debe funcionar en README, wiki o blog.
Úsalo para README, notas de API, RFCs y artículos de ayuda. La idea es crear un ciclo corto de edición, previsualización y revisión antes de publicar.
Una demo pequeña para pegar primero
No empieces con todo el contenido de producción. Usa primero un fragmento pequeño para validar sintaxis, etiquetas y layout.
Cuando la primera vista funcione, añade nombres reales de servicios, campos, actores o dependencias.
# Checkout flow
The API creates an order, then asks the payment service to confirm it.
```mermaid
sequenceDiagram
participant User
participant Store
participant Payment
User->>Store: POST /orders
Store->>Payment: Create payment intent
Payment-->>Store: Confirmed
Store-->>User: Order receipt
```Cómo revisar la previsualización
Revisa como si fueras un compañero leyendo la página. ¿Responde una pregunta clara? ¿La fuente se podrá editar después?
Si viene de IA, revisa nombres, dirección, agrupación y relaciones faltantes.
Errores comunes
El error más común es intentar explicarlo todo en un solo diagrama. Separa flujo de petición, datos, infraestructura y salida de publicación.
Otro error es exportar solo una imagen. Guarda el texto fuente junto al SVG o PNG.
Checklist antes de publicar
Antes de publicar, verifica nitidez, etiquetas largas y que el artículo incluya una entrada reproducible.
La página funciona mejor cuando muestra entrada, previsualización y decisión tomada después de revisarla.