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:
flowchart TDsignifica de arriba abajo. UsaLRpara de izquierda a derecha. La palabragraphtambién funciona en lugar deflowchart.Start[Write the note]crea un recuadro.Startes el nombre corto. El texto entre corchetes es la etiqueta.- Las llaves
{ }crean una forma de decisión, un rombo. -->dibuja una flecha. El texto entre barras verticales, como|Yes|, pone una etiqueta a la flecha.
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
```
participant U as Usercrea una columna llamada User. El nombre corto esU.->>es una flecha continua.-->>es una flecha de puntos, que se usa a menudo para las respuestas.- El texto después de los dos puntos es el mensaje.
- Los mensajes se dibujan de arriba abajo, en el orden en que los escribes.
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:
- Diagrama de Gantt: tareas en una línea de tiempo.
- Diagrama de clases: las clases del código y cómo se conectan.
- Diagrama de estados: los estados de algo y cómo pasa de uno a otro.
- Diagrama entidad-relación: tablas de una base de datos y sus vínculos.
- Recorrido del usuario: los pasos que da una persona.
- Mapa mental: ideas que se ramifican desde un centro.
- Línea de tiempo: eventos por orden de fecha.
- Gráfico de Git: ramas y commits.
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
- Una pequeña errata rompe todo el diagrama. Las palabras clave desconocidas o mal escritas impiden que se dibuje. Si ves un error o texto sin formato, comprueba primero la primera línea y las flechas.
- Caracteres especiales en las etiquetas. Los corchetes, los paréntesis y caracteres parecidos pueden confundir al analizador. Pon la etiqueta entre comillas:
A["Save (draft)"]. - La palabra
enden un diagrama de flujo. En minúsculas,endrompe un diagrama de flujo. EscribeEndoEND, o pon la palabra entre comillas. También puede dar problemas en los diagramas de secuencia. - Valla incorrecta. El lenguaje después de los acentos graves debe ser
mermaid. Sin él, el lector ve un bloque de código normal.
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)