Diagramas Mermaid en Markdown: expórtalos a PDF

Por Fazt · Actualizada el 7 de octubre de 2026

Un diagrama suele explicar un proceso mejor que tres párrafos, pero dibujarlo con un programa de gráficos obliga a exportar una imagen, pegarla y rehacerla cada vez que algo cambia. Con Mermaid describes el diagrama en unas pocas líneas de texto dentro de tu Markdown y el editor lo dibuja. Esta guía te da ejemplos para copiar de los tipos de diagrama más útiles y explica qué les pasa cuando exportas un PDF.

Por qué dibujar diagramas con texto

Mermaid es una librería de código abierto que convierte una descripción breve en texto en un diagrama. Eso tiene ventajas prácticas:

Los cambios llevan segundos. Renombrar un paso o añadir una rama es cambiar una línea, y la disposición se recalcula sola.
El diagrama vive dentro del documento, así que no hay un archivo de imagen que mantener al día, y los cambios se revisan fácilmente con control de versiones.
Funciona en muchos sitios. GitHub, GitLab y Obsidian muestran los mismos bloques, así que una sola fuente sirve para un README, para tus notas y para un PDF.

A cambio, pierdes algo de control: Mermaid decide dónde va cada caja. Para documentación y apuntes, suele compensar.

Tu primer diagrama

En el editor de Markdown a PDF, un diagrama es un bloque de código delimitado cuyo lenguaje es mermaid. La primera línea indica el tipo de diagrama y el resto lo describe:

```mermaid
flowchart LR
  A[Markdown] --> B[Vista previa] --> C[PDF]
```

La vista previa vuelve a dibujar el diagrama mientras escribes. El primer diagrama de un documento puede tardar un momento en aparecer, porque el editor solo carga la librería Mermaid cuando hace falta. Escribe mermaid en minúsculas: un bloque marcado como Mermaid se muestra como código normal.

Ejemplos para copiar

Todos se muestran tal cual. Pega uno y cambia las etiquetas por las tuyas.

Diagrama de flujo: procesos y decisiones

```mermaid
flowchart TD
  A[Solicitud recibida] --> B{¿Aprobada?}
  B -->|Sí| C[Pedir las piezas]
  B -->|No| D[Responder con los motivos]
  C --> E[Programar el trabajo]
```

TD significa de arriba abajo y LR, de izquierda a derecha. Los corchetes dibujan una caja, las llaves un rombo de decisión y |texto| pone una etiqueta en una flecha.

Diagrama de secuencia: quién habla con quién

```mermaid
sequenceDiagram
  participant C as Cliente
  participant T as Tienda
  participant P as Pasarela de pago
  C->>T: Hace el pedido
  T->>P: Cobra la tarjeta
  P-->>T: Pago confirmado
  T-->>C: Confirmación del pedido
  Note over T,P: Hasta 3 reintentos
```

Las flechas continuas (->>) suelen indicar peticiones y las discontinuas (-->>), respuestas. Cada mensaje necesita dos puntos antes de su texto.

Diagrama de Gantt: un plan de proyecto

```mermaid
---
config:
  gantt:
    useWidth: 640
---
gantt
  title Relanzamiento de la web
  dateFormat YYYY-MM-DD
  section Diseño
  Wireframes    :a1, 2026-11-02, 10d
  Diseño visual :a2, after a1, 8d
  section Desarrollo
  Programación  :b1, after a2, 15d
  Pruebas       :b2, after b1, 5d
```

Cada tarea tiene un identificador, un inicio (una fecha o after seguido de otra tarea) y una duración. La cabecera config entre las líneas --- fija el ancho del diagrama, por motivos que verás más abajo.

Línea de tiempo: hitos

```mermaid
timeline
  title Historia del proyecto
  2023 : Idea y primer prototipo
  2024 : Beta con 20 clientes
       : Primer plan de pago
  2025 : Versión 2.0
```

Diagrama entidad-relación: modelos de datos

```mermaid
erDiagram
  CLIENTE ||--o{ PEDIDO : hace
  PEDIDO ||--|{ LINEA_PEDIDO : contiene
  PRODUCTO ||--o{ LINEA_PEDIDO : "aparece en"
  CLIENTE {
    int id
    string nombre
    string email
  }
```

|| significa exactamente uno, o{ cero o más y |{ uno o más. Para diseños orientados a objetos, classDiagram funciona de forma parecida.

Gráfico circular y mapa mental

```mermaid
pie title Tiempo por fase
  "Investigación" : 20
  "Diseño" : 30
  "Desarrollo" : 40
  "Pruebas" : 10
```

```mermaid
mindmap
  root((Viaje a Lisboa))
    Transporte
      Vuelos
      Traslado al aeropuerto
    Alojamiento
      Hotel
      Barrio
    Presupuesto
```

Los valores del gráfico circular no tienen que sumar 100. En un mapa mental, la jerarquía se define solo con la sangría, así que mantenla uniforme.

Mermaid también dibuja diagramas de estados, recorridos de usuario, grafos de Git, gráficos XY y tableros Kanban. El editor usa Mermaid 12, y la documentación oficial (en inglés) explica todos los tipos.

Cómo quedan los diagramas en papel

Tamaño y ancho de página

Las páginas se imprimen en vertical, y la columna de texto mide unos 17 cm de ancho en A4 con márgenes normales. Un diagrama que cabe se imprime a su tamaño natural, centrado y sin ampliarse. Uno más ancho se reduce hasta el ancho de la columna, y su texto encoge con él:

Un diagrama de flujo de izquierda a derecha con más de tres o cuatro cajas seguidas ya es demasiado ancho. Cambiar LR por TD suele ser el mejor arreglo.
Cada participante de un diagrama de secuencia añade unos 5 cm; con cinco o seis, las etiquetas quedan pequeñas.
Las líneas de tiempo crecen a lo ancho con cada periodo, así que usa textos breves en los eventos.

El ajuste Tamaño de letra del panel Estilo no afecta a las etiquetas de los diagramas; solo se hacen más pequeñas cuando el diagrama se reduce. Eso sí, la mayoría de los tipos usan la fuente del texto de tu tema, así que encajan con el resto del documento.

Los diagramas de Gantt necesitan un ancho fijo

Mermaid da a los diagramas de Gantt el ancho de la ventana del navegador, no el de la página. En una pantalla ancha el diagrama sale muy ancho y luego se reduce para caber, con un texto demasiado pequeño para leerse. El ajuste useWidth del ejemplo anterior fija el ancho; 640 coincide con la columna en A4 o Carta con márgenes normales.

Saltos de página con diagramas grandes

El editor intenta que cada diagrama quede en una sola página. Si un diagrama no cabe en el espacio que queda, pasa a la página siguiente, lo que puede dejar un hueco y separarlo de su título. Dos costumbres ayudan:

Pon  en una línea propia antes del título de una sección con un diagrama grande, para que ambos empiecen juntos la página siguiente.
Haz que cada diagrama ocupe menos de una página. Uno más alto no puede mantenerse entero: el navegador lo corta donde termina la página, a veces por la mitad de una caja. Mejor divídelo, por ejemplo en un diagrama por fase.

Colores, temas y modo oscuro

Los diagramas usan el tema neutral de Mermaid: cajas gris claro, texto oscuro y líneas grises, que se imprimen bien incluso en blanco y negro. No siguen los colores que elijas en el panel Estilo, y el modo oscuro no les afecta: la página de la vista previa siempre es blanca y el PDF siempre se imprime en claro. Para cambiar el estilo de un solo diagrama, añade una cabecera de configuración a su bloque:

```mermaid
---
config:
  theme: forest
---
flowchart LR
  A[Borrador] --> B[Revisión] --> C[Publicación]
```

default, forest y base añaden color, y neutral recupera el aspecto estándar. Evita dark para imprimir: sus cajas negras y flechas pálidas están pensadas para un fondo oscuro y en papel gastan mucha tinta.

¿Vector o imagen?

Con Descargar PDF y Guardar como PDF en el diálogo de impresión, los diagramas siguen siendo gráficos vectoriales: las líneas se ven nítidas con cualquier zoom y las etiquetas son texto real que puedes seleccionar y buscar. (En Chrome, las cajas con sombra suave se incrustan como imágenes de alta resolución, algo que no notarás en papel). Más → PDF rápido (imagen), en cambio, convierte cada página en una imagen: no se puede seleccionar nada, el resultado es menos nítido y las etiquetas de los diagramas pueden pasar a una fuente genérica. Más → Descargar .html también conserva los diagramas como gráficos vectoriales.

Cuando un diagrama no se dibuja

Si Mermaid no puede leer un bloque, el diagrama se sustituye por un texto rojo que empieza por Mermaid:. Los errores de sintaxis indican el número de línea dentro del diagrama y una marca donde se detuvo la lectura; el resto del documento se sigue mostrando. Corrígelo antes de exportar, porque el PDF contiene exactamente lo que muestra la vista previa. Las causas habituales:

“No diagram type detected”: falta la primera línea o está mal escrita (flowchar, sequencediagram). Las palabras clave distinguen mayúsculas y minúsculas.
Paréntesis o corchetes dentro de una etiqueta, como en A[Enviar factura (PDF)], dan un error que termina en got 'PS'. Pon la etiqueta entre comillas: A["Enviar factura (PDF)"].
Un nodo llamado end rompe los diagramas de flujo, porque end es una palabra clave. Escribe End o úsala solo como etiqueta: Fin[end].
Un mensaje de secuencia sin dos puntos (Ana->>Luis Hola) da Expecting 'TXT', got 'NEWLINE'.
“Invalid date” en un diagrama de Gantt: una fecha no existe o no coincide con la línea dateFormat.
Las comillas tipográficas (« », “ ”) que se cuelan al pegar desde un procesador de textos no cuentan como comillas. Usa comillas rectas en el código del diagrama.

¿Sigues atascado? Borra líneas desde el final del bloque hasta que el diagrama reaparezca; la última que quitaste es la culpable.

Consejos para diagramas que se lean bien en papel

Etiquetas cortas. Entre dos y cinco palabras por caja. Las cajas de los diagramas de flujo reparten el texto largo en varias líneas; para elegir tú el corte, usa <br>: A["Primera línea<br>segunda línea"].
Menos de 15 cajas. Divide un proceso grande en una vista general y uno o dos diagramas de detalle.
Presenta cada diagrama con una frase que diga en qué fijarse.
Deja que las etiquetas lleven el significado, no solo el color: el PDF puede acabar impreso en blanco y negro.
Usa %% para comentarios. Esas líneas se quedan en el código pero no se dibujan.
Revisa la vista previa con el tema definitivo. Mermaid mide las etiquetas antes de aplicar la fuente del documento, así que con las fuentes con serifa, más anchas, de Classic y Editorial, una etiqueta corta de flecha puede perder su última letra. Si pasa, cambia a un tema sin serifa como Modern o Clean.

Todo, diagramas incluidos, se genera en tu navegador; no se sube nada. Para el resto de la sintaxis, consulta la guía de Markdown. Si tus diagramas están en Obsidian, la guía para exportar notas de Obsidian y Notion a PDF repasa el resto de la sintaxis que conviene limpiar.