mermaid markdown diagrams flowchart documentation

Mermaid en Markdown: crea diagramas de flujo, de secuencia y mucho más

Aprenda la sintaxis Mermaid para Markdown con ejemplos de diagramas de flujo, secuencias, clases, Gantt, mapas mentales y diagramas ER listos para copiar, además de orientación sobre vista previa, exportación, compatibilidad y accesibilidad.

W
WordToMD Equipo
·

Los diagramas técnicos a menudo se vuelven obsoletos porque editarlos requiere encontrar el archivo de diseño original, abrir una aplicación separada y exportar otra imagen.Mermaid adopta un enfoque diferente: el diagrama se define como texto y se almacena junto a la documentación.

Para agregar Mermaid a Markdown, coloque la definición del diagrama dentro de un bloque de código cercado con el mermaid identificador de idioma.Utilice el Vista previa de diagramas Mermaid para representar la sintaxis localmente, corregir errores, copiar la valla Markdown completa o descargar un SVG.

Esta guía comienza con un pequeño diagrama de flujo y avanza hacia diagramas de secuencia, clase, Gantt, mapa mental y entidad-relación.

Mermaid en 30 Segundos

Un bloque básico Mermaid tiene el siguiente aspecto:

```mermaid
flowchart LR
  Draft --> Review
  Review --> Publish
```

La valla de apertura le dice a un renderizador compatible que el contenido tiene la sintaxis Mermaid. flowchart LR selecciona un diagrama de flujo ordenado de izquierda a derecha.Las líneas restantes definen nodos y conexiones.

Si el destino no soporta Mermaid, los lectores normalmente verán un bloque de código en lugar de un diagrama.Ese respaldo preserva la fuente, pero no reemplaza la verificación de la compatibilidad antes de la publicación.

¿Por qué utilizar diagramas basados en texto?

Mermaid es especialmente útil cuando un diagrama:

  • pertenece a la documentación controlada por versión;
  • cambios junto con el código o procedimientos;
  • necesita diferencias significativas en las solicitudes de extracción;
  • utiliza formas y relaciones estándar;
  • debe poder editarse sin un archivo de diseño propietario;
  • debe regenerarse en temas claros y oscuros.

Es menos adecuado para ilustraciones detalladas, diseños con píxeles perfectos, anotaciones a mano alzada o diseños visuales que requieren una colocación manual precisa.En esos casos, utilice una herramienta de dibujo y exporte una imagen o SVG accesible.

Ejemplo 1: Un diagrama de flujo

Los diagramas de flujo describen un proceso, decisión o regla de enrutamiento.

```mermaid
flowchart TD
  A[Choose a DOCX file] --> B{File valid?}
  B -->|Yes| C[Convert to Markdown]
  B -->|No| D[Show an error]
  C --> E[Review the output]
  E --> F[Copy or download]
```

Sintaxis clave:

  • TD significa de arriba a abajo.
  • LR significa de izquierda a derecha.
  • [Text] crea un nodo de proceso rectangular.
  • {Text} crea un nodo de decisión.
  • --> crea una conexión direccional.
  • -->|Label| añade texto a una conexión.

Utilice ID de nodo cortos y estables, como A or validate.Mantenga la etiqueta visible entre corchetes para que cambiar el texto no requiera cambiar todas las conexiones.

Agregar un subgrafo

Pasos relacionados con el grupo de subgrafos:

```mermaid
flowchart LR
  subgraph Browser
    Upload[Choose file] --> Convert[Convert locally]
  end

  subgraph Output
    Preview[Preview Markdown] --> Save[Download file]
  end

  Convert --> Preview
```

Utilice subgrafos cuando la agrupación comunique propiedad, límites del sistema o fases.No agregues una caja simplemente como decoración.

Ejemplo 2: Un diagrama de secuencia

Los diagramas de secuencia muestran las interacciones en orden temporal.Funcionan bien para llamadas de API, autenticación, flujos de trabajo del navegador y sistemas controlados por eventos.

```mermaid
sequenceDiagram
  autonumber
  actor User
  participant Browser
  participant Converter

  User->>Browser: Select DOCX file
  Browser->>Converter: Pass local file data
  Converter-->>Browser: Return Markdown
  Browser-->>User: Show editable preview
```

Flechas comunes:

  • ->> envía un mensaje sólido.
  • -->> envía una respuesta discontinua.
  • participant declara un sistema o servicio.
  • actor declara un rol humano o externo.
  • autonumber etiqueta las interacciones en orden.

Centrarse en un escenario.Un diagrama de secuencia que intenta mostrar cada alternativa y cada función interna se vuelve más difícil de entender que el código.

Mostrar una ruta alternativa

```mermaid
sequenceDiagram
  participant Client
  participant API

  Client->>API: POST /documents
  alt Valid request
    API-->>Client: 201 Created
  else Invalid request
    API-->>Client: 400 Bad Request
  end
```

Utilización alt, else, y end para ramas significativas.Si la rama requiere varias páginas de explicación, enlace a la prosa debajo del diagrama.

Ejemplo 3: Un diagrama de clases

Los diagramas de clases describen tipos, propiedades, operaciones, herencia y relaciones.

```mermaid
classDiagram
  class Document {
    +String name
    +String content
    +convert()
  }

  class MarkdownDocument {
    +String frontmatter
    +render()
  }

  Document <|-- MarkdownDocument
```

Este ejemplo establece que MarkdownDocument hereda de Document.Utilice diagramas de clases para un modelo conceptual, no como un reemplazo automático de la documentación de referencia completa API.

Los buenos diagramas de clases omiten detalles que no ayudan al lector a comprender el diseño.Mostrar cada campo privado puede convertir el diagrama en una versión del código fuente con menos capacidad de búsqueda.

Ejemplo 4: Un diagrama de Gantt

Los diagramas de Gantt muestran tareas a lo largo del tiempo.Son útiles para planes de lanzamiento, migraciones y proyectos de documentación.

```mermaid
gantt
  title Documentation migration
  dateFormat YYYY-MM-DD

  section Preparation
  Inventory content :done, inventory, 2026-11-03, 3d
  Define templates  :done, templates, after inventory, 2d

  section Migration
  Convert documents :active, convert, 2026-11-08, 7d
  Editorial review  :review, after convert, 5d

  section Publish
  Final validation  :validate, after review, 2d
```

Mantenga las fechas explícitas y utilice ID de tarea cuando una tarea dependa de otra.Recuerde que un diagrama almacenado en la documentación no se actualizará solo cuando cambie el cronograma real del proyecto.Asigne propiedad para mantenerlo actualizado.

Ejemplo 5: Un mapa mental

Los mapas mentales organizan ideas en torno a un tema central.

```mermaid
mindmap
  root((Markdown quality))
    Structure
      Headings
      Lists
      Tables
    Accessibility
      Alt text
      Link text
      Reading order
    Publishing
      GitHub
      Obsidian
      Documentation site
```

Los mapas mentales son más eficaces durante la planificación o como descripción general de alto nivel.Son menos útiles para relaciones precisas porque la estructura de árbol puede implicar una jerarquía donde los conceptos reales se superponen.

Ejemplo 6: Un diagrama entidad-relación

Los diagramas ER describen entidades de datos y sus relaciones.

```mermaid
erDiagram
  AUTHOR ||--o{ DOCUMENT : writes
  DOCUMENT ||--o{ REVISION : contains
  DOCUMENT }o--o{ TAG : uses

  AUTHOR {
    string id
    string name
  }

  DOCUMENT {
    string id
    string title
    datetime published_at
  }
```

Utilice un diagrama ER para explicar el modelo y un esquema o archivo de migración para definir la implementación.Un diagrama puede omitir índices, restricciones y campos que no son relevantes para la explicación actual.

Vista previa Mermaid antes de publicar

Escribir diagramas directamente en un documento Markdown largo hace que los errores de sintaxis sean difíciles de aislar.Un bucle de vista previa enfocado es más rápido:

  1. Abre el Vista previa de diagramas Mermaid.
  2. Pegue sólo la definición del diagrama, sin la valla de código exterior.
  3. Renderizar el diagrama.
  4. Leer cualquier error de sintaxis y corregir el área referenciada.
  5. Copiar el vallado generado Markdown.
  6. Descargar el SVG cuando el destino necesite un recurso estático.
  7. Probar el Markdown final en su plataforma real.

La vista previa se muestra en su navegador con una configuración de seguridad estricta.Las devoluciones de llamadas de diagramas y otros comportamientos interactivos pueden desactivarse incluso si otra instalación Mermaid los permite.Ese comportamiento conservador es apropiado para una herramienta de vista previa general.

Errores comunes Mermaid

Falta el tipo de diagrama

Incorrecto:

A --> B

Correcto:

flowchart LR
  A --> B

La primera línea identifica la gramática del diagrama.

La puntuación en una etiqueta interrumpe el análisis

Cotizar etiquetas complejas:

flowchart LR
  A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]

Esto es particularmente útil para paréntesis, puntuación y etiquetas que se parecen a la sintaxis.

Se utiliza inesperadamente un Word reservado

Mermaid tienen palabras clave.La documentación oficial del diagrama de flujo advierte específicamente que las minúsculas end puede romper un diagrama de flujo.Escríbalo en mayúscula o coloque el texto visible dentro de una etiqueta de nodo entre comillas:

flowchart LR
  Start --> Finish["End"]

La barrera del código es incorrecta

El identificador de idioma va inmediatamente después de las comillas invertidas de apertura:

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

No aplique sangría a la valla completa a menos que la sintaxis circundante Markdown así lo requiera.

Funciona en una plataforma pero no en otra

Mermaid evoluciona y las plataformas pueden utilizar diferentes renderizadores, versiones, configuraciones de seguridad y tipos de diagramas habilitados.Una característica de sintaxis compatible con la versión más reciente Mermaid puede fallar en una plataforma que utiliza otra implementación o una versión anterior.

Prefiere una sintaxis ampliamente compatible para documentos que se mueven entre plataformas.Pruebe formas avanzadas, temas, directivas y tipos de diagramas más nuevos en cada destino requerido.

Compatibilidad de plataforma

La compatibilidad debe probarse en lugar de asumirse:

Plataforma de trabajoEnfoque documentado actualNota importante
GitHubUtilice un vallado mermaid blockGitHub representación de documentos en archivos Markdown, incidencias, debates, solicitudes de extracción y wikis
GitLab (en inglés)Usar un bloque de código Mermaid en GitLab Flavored MarkdownGitLab documenta su versión Mermaid compatible;las instalaciones autogestionadas pueden diferir
ObsidianUtilice un vallado mermaid en una notaObsidian y las funciones compatibles pueden cambiar entre versiones
Material para MkDocsConfigurar una valla a medida MermaidLa integración del tema nativo requiere documentación pymdownx.superfences configuration
Analizador genérico MarkdownA menudo muestra sólo códigoMermaid normalmente requiere un complemento de integración o compilación JavaScript

Consulte la documentación oficial actual antes de confiar en una característica más nueva:

Para un sitio de documentación que usted controle, fije la versión de dependencia Mermaid y pruebe las actualizaciones.De lo contrario, un cambio menor de sintaxis puede alterar los diagramas en todo el sitio.

Mermaid y Accesibilidad

Un SVG renderizado no comunica automáticamente su significado a todos los lectores.Trate el diagrama como un resumen visual y proporcione una explicación equivalente en prosa cercana.

Para el diagrama de flujo de conversión anterior, agregue texto como:

El usuario selecciona un archivo DOCX.Los archivos válidos se convierten localmente y se muestran para su revisión;Los archivos no válidos producen un error.A continuación, el usuario puede copiar o descargar el Markdown reseñado.

Prácticas de accesibilidad:

  • introducir lo que explica el diagrama;
  • resumir la conclusión después de diagramas complejos;
  • no codifica el significado únicamente con el color;
  • utilizar etiquetas legibles en lugar de abreviaturas internas;
  • mantener suficiente contraste en temas claros y oscuros;
  • evitar diagramas que requieran una interacción precisa del ratón;
  • proporcionar un texto o una tabla alternativa para información esencial;
  • exporte SVG con cuidado cuando el archivo estático deba llevar un nombre accesible.

El código fuente es útil para los autores, pero no es necesariamente una buena alternativa de texto para los lectores.

Diseño de diagramas que sean legibles

Mantener un propósito por diagrama

Un diagrama debe responder a una pregunta como "¿Qué sucede después de una solicitud fallida?"o "¿A qué servicio pertenece cada almacén de datos?"Si intenta explicar todo el sistema, divídalo.

Prefiero etiquetas cortas

Poner explicaciones detalladas en prosa.Las etiquetas largas fuerzan nodos estrechos, ajustes de líneas incómodos y diagramas grandes en las pantallas de los móviles.

Usar la dirección intencionalmente

El flujo de izquierda a derecha funciona bien para procesos cortos y rutas de solicitud.El flujo de arriba a abajo suele adaptarse mejor a las pantallas estrechas.Obtenga una vista previa de ambos antes de comprometerse.

Limitar el estilo visual

Los colores personalizados pueden entrar en conflicto con el modo oscuro o los temas de la plataforma.Comience con los valores predeterminados del renderizador.Agregue estilos solo cuando comuniquen significado y sigan siendo legibles en todos los temas requeridos.

Mantener la fuente cerca de su explicación

Almacenar el bloque Mermaid en el mismo archivo Markdown cuando sea posible.Eso hace que la prosa y el diagrama cambien juntos en una sola reseña.

Mermaid frente a una imagen estática

Elija Mermaid cuando:

  • el diagrama cambia frecuentemente;
  • son valiosas;
  • el diseño utiliza tipos de diagramas estándar;
  • la plataforma de publicación genera Mermaid de forma fiable.

Elija SVG o PNG cuando:

  • el diseño requiere un trazado manual preciso;
  • el destino no rinde Mermaid;
  • la apariencia exacta debe permanecer fija;
  • el uso compartido externo requiere un activo independiente.

Un híbrido útil es mantener la fuente Mermaid y exportar un SVG para destinos que no pueden procesarlo.Mantenga la fuente junto al activo exportado y documente cómo regenerarlo.

Utilización Markdown a imagen para contenido renderizado Markdown que se puede compartir, o descargar SVG directamente desde Vista previa de diagramas Mermaid cuando el propio diagrama sea el activo.

FAQ

¿Es Mermaid parte de la norma Markdown?

N° A vallado mermaid es una extensión reconocida por aplicaciones y sistemas de compilación compatibles.Un analizador básico Markdown puede representarlo como código ordinario.

¿GitHub representa diagramas Mermaid?

Sí.La documentación de GitHub describe la representación de Mermaid en archivos Markdown y varias superficies de colaboración.Pruebe la sintaxis más nueva porque GitHub controla el renderizador implementado y la configuración de seguridad.

¿Puedo utilizar Mermaid en Obsidian?

Obsidian documenta bloques de diagramas vallados estilo Mermaid en notas.La compatibilidad con funciones puede cambiar con el renderizador de la aplicación, así que verifique los tipos de diagramas complejos o recién introducidos en su versión instalada.

¿Puede Mermaid sustituir la documentación de arquitectura?

No. Un diagrama es una vista de un sistema.Combínelo con decisiones, propiedad, restricciones, comportamiento de falla y enlaces a interfaces o esquemas autorizados.

¿Por qué mi diagrama se muestra diferente en modo oscuro?

Las plataformas pueden aplicar diferentes temas Mermaid, variables CSS, fuentes y fondos.Evite los colores codificados hasta que haya probado ambos temas.

¿Debo enviar archivos SVG exportados?

Confirme un SVG cuando el destino de publicación necesite un recurso estático o el resultado renderizado deba permanecer estable.Conserve también la fuente Mermaid y un proceso de regeneración documentado para evitar que las dos versiones se desvíen.

¿Es seguro Mermaid para diagramas confidenciales?

La confidencialidad depende del editor y del flujo de trabajo de publicación.La vista previa de WordToMD muestra el diagrama en su navegador, pero la publicación de Markdown o SVG en un repositorio o sitio sigue los controles de acceso de ese destino.

Conclusión

Mermaid hace que los diagramas sean mantenibles porque la fuente vive con el Markdown.Comience con un pequeño bloque cercado, elija el tipo de diagrama que coincida con la pregunta, obtenga una vista previa de la sintaxis y pruébelo en el renderizador final.Utilice prosa para explicar el significado esencial y exporte SVG cuando un destino necesite un activo estático.

Pruebe los ejemplos del Vista previa de diagramas Mermaid, edite la documentación circundante en el Markdown Editory mantenga el diagrama lo suficientemente enfocado como para que un futuro colaborador pueda entenderlo y actualizarlo sin tener que volver a dibujar toda la página.