Diagramas de Mermaid en Markdown

Mermaid es una forma de dibujar diagramas con texto. Escribes unas pocas líneas cortas. Un lector que admita Mermaid las convierte en una imagen: un diagrama de flujo, una línea de tiempo, un gráfico.

Puedes mantener el diagrama dentro de un archivo Markdown normal. No hay ninguna imagen que exportar ni ninguna herramienta de dibujo que abrir. Para cambiar el diagrama, cambias el texto.

El bloque de código mermaid

Un diagrama de Mermaid vive en un bloque de código delimitado. Una valla son tres acentos graves. Después de la valla de apertura, escribe mermaid como lenguaje:

```mermaid
flowchart LR
    A --> B
```

La primera línea dentro del bloque indica de qué tipo de diagrama se trata. Aquí es flowchart LR. Todo lo que viene después de esa línea describe el diagrama.

Las líneas que empiezan por %% son comentarios. El lector las ignora.

Ejemplo 1: un diagrama de flujo con una decisión

```mermaid
flowchart TD
    Start[Write the note] --> Check{Is it clear?}
    Check -->|Yes| Publish[Share it]
    Check -->|No| Edit[Rewrite it]
    Edit --> Check
```

Cómo leerlo:

Ejemplo 2: un diagrama de secuencia

Un diagrama de secuencia muestra quién habla con quién, por orden.

```mermaid
sequenceDiagram
    participant U as User
    participant S as Server
    U->>S: Open the page
    S-->>U: Send the page
    U->>S: Log in
    S-->>U: Welcome
```

Ejemplo 3: un gráfico circular

```mermaid
pie title Time spent on a project
    "Writing" : 40
    "Reading" : 25
    "Meetings" : 15
    "Other" : 20
```

Cada porción es una etiqueta entre comillas, dos puntos y un número. El número debe ser mayor que cero.

Otros tipos de diagrama

Mermaid puede dibujar muchos más tipos. Los más comunes:

Cada tipo tiene su propia primera palabra y sus propias reglas. La documentación de Mermaid tiene una página para cada uno.

Dónde se dibujan los diagramas de Mermaid

GitHub dibuja los bloques de Mermaid en archivos Markdown, incidencias, debates, pull requests y wikis. Solo necesitas el bloque de código mermaid. Muchos editores de Markdown y apps de notas también admiten Mermaid, pero no todos.

Cuando un lector no admite Mermaid, normalmente trata el bloque como cualquier otro código. Ves el texto que escribiste, no una imagen. No se pierde nada. Simplemente no se dibuja.

Errores comunes

No hace falta sangrar. La mayoría de la gente sangra las líneas dentro de un diagrama solo porque así es más fácil de leer.

Los chats de IA y los agentes escriben Mermaid

Los chats de IA y los agentes de programación suelen poner Mermaid en planes, especificaciones y notas de diseño. Un diagrama de flujo es una forma rápida de mostrar pasos. Un diagrama de secuencia muestra cómo hablan entre sí las partes de un sistema.

Si un chat te da un diagrama, copia el bloque de código entero, incluidas las vallas, en tu archivo Markdown. Si el diagrama no se dibuja, compáralo con los errores de arriba. Las etiquetas cortas y una sola idea por diagrama hacen que el texto sea más fácil de corregir.

Cómo leer diagramas de Mermaid

PilcrowMD dibuja diagramas de Mermaid en Android y en Mac, sin necesidad de internet. En Android, toca un diagrama para verlo a pantalla completa. En Mac, Quick Look, Comparar y PDF muestran el bloque de código en lugar de la imagen.

Preguntas frecuentes

¿Tengo que instalar algo para escribir Mermaid? No. Escribes texto sin formato en un bloque de código. Solo necesitas un lector que lo dibuje.

¿Por qué veo código en lugar de un diagrama? O el lector no admite Mermaid, o el diagrama tiene un error de sintaxis. Comprueba que el bloque empieza por mermaid y que la primera línea nombra un tipo de diagrama real.

¿Puedo cambiar el aspecto de un diagrama? Sí. Mermaid tiene opciones de colores, formas y diseño. Empieza con los valores predeterminados. Bastan para la mayoría de las notas.

También en Mac: PilcrowMD para Mac (beta)