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:
TDsignifica de arriba a abajo.LRsignifica 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.participantdeclara un sistema o servicio.actordeclara un rol humano o externo.autonumberetiqueta 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:
- Abre el Vista previa de diagramas Mermaid.
- Pegue sólo la definición del diagrama, sin la valla de código exterior.
- Renderizar el diagrama.
- Leer cualquier error de sintaxis y corregir el área referenciada.
- Copiar el vallado generado Markdown.
- Descargar el SVG cuando el destino necesite un recurso estático.
- 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 trabajo | Enfoque documentado actual | Nota importante |
|---|---|---|
| GitHub | Utilice un vallado mermaid block | GitHub 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 Markdown | GitLab documenta su versión Mermaid compatible;las instalaciones autogestionadas pueden diferir |
| Obsidian | Utilice un vallado mermaid en una nota | Obsidian y las funciones compatibles pueden cambiar entre versiones |
| Material para MkDocs | Configurar una valla a medida Mermaid | La integración del tema nativo requiere documentación pymdownx.superfences configuration |
| Analizador genérico Markdown | A menudo muestra sólo código | Mermaid 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:
- GitHub: Crear diagramas
- Con sabor a GitLab Markdown
- Obsidian: Sintaxis de formato avanzada
- Material para MkDocs: Diagramas
- Mermaid referencia de sintaxis
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.