Cómo abrir un archivo .mmd
Un archivo .mmd es un archivo de texto plano que contiene un diagrama de Mermaid. No es una imagen ni un formato binario: puedes abrirlo con cualquier editor de texto y leerlo. Para verlo como diagrama, suéltalo en el recuadro de abajo. Se dibuja en tu navegador y no se sube nada a ningún servidor.
Suelta aquí un archivo .mmd
También acepta .mermaid, .md y .txt. El archivo se lee en tu navegador; nunca se sube.
¿Qué es un archivo .mmd?
Mermaid es una sintaxis de texto para diagramas. Tú describes el diagrama con palabras y el motor lo dibuja, igual que Markdown describe el formato y el motor produce la página. Un archivo .mmd contiene ese texto y nada más: ni estilos, ni datos de imagen, ni metadatos.
Esa es toda la razón de ser del formato. Al ser texto, un diagrama puede vivir en un repositorio de Git junto al código que describe, y un cambio aparece como un diff legible en lugar de como un binario reemplazado. Esto es un archivo .mmd completo y válido:
flowchart LR
Commit[Push a main] --> Build[Ejecutar las pruebas]
Build -->|pasa| Deploy[Desplegar a producción]
Build -->|falla| Aviso[Avisar al autor]
Deploy --> Humo[Prueba de humo]
Humo --> Fin[Release publicada]Qué abre un archivo .mmd
La versión corta: casi nada abre un .mmd haciendo doble clic, porque la extensión no está asociada a ninguna aplicación. Lo que hace falta de verdad es algo que dibuje Mermaid. Abajo está lo que he comprobado, y dónde no funciona.
Esta páginaFunciona
Dibuja el archivo directamente
Suelta el archivo en el recuadro de arriba y obtienes el diagrama. No hay paso de subida: el archivo se lee en tu navegador con la File API y se dibuja localmente, así que también sirve para diagramas que no tienes permiso para enviar a un tercero.
Si quieres cambiar el diagrama y no solo mirarlo, usa el enlace que hay debajo de la vista previa para abrirlo en el editor.
Cualquier editor de textoFunciona
Muestra el código fuente, no el diagrama
Bloc de notas, TextEdit, vim, lo que sea. Un archivo .mmd es texto UTF-8, así que verás el contenido de inmediato. No verás un diagrama, y no está roto: simplemente no hay ninguna imagen dentro del archivo que mostrar.
Es la forma más rápida de comprobar si un archivo que te han enviado es realmente Mermaid: ábrelo y mira si la primera línea no vacía es una palabra clave de diagrama como flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram o gantt.
GitHubNo funciona
Dibuja bloques ```mermaid dentro de Markdown, no archivos .mmd sueltos
GitHub dibuja Mermaid dentro de bloques de código delimitados. Su documentación dice exactamente dónde: incidencias, Discussions, pull requests, wikis y archivos Markdown. Un archivo .mmd suelto no está en esa lista, y abrirlo en el explorador de archivos del repositorio muestra el texto fuente.
Así que, si quieres un diagrama visible en GitHub, el diagrama tiene que estar dentro de un bloque ```mermaid en un archivo .md, no en un .mmd propio. Mantener un .mmd para la fuente y repetir el mismo contenido en el README es una duplicación habitual y razonable.
GitLabNo funciona
Dibuja bloques ```mermaid, no archivos .mmd sueltos, y con un Mermaid más antiguo
Mismo esquema que GitHub: Mermaid se dibuja dentro de bloques delimitados en Markdown, incidencias, merge requests y wikis, pero no está documentado que se dibuje un archivo .mmd suelto.
Hay una segunda cosa que conviene saber, porque provoca confusión real. GitLab.com indica que admite la versión 10 de Mermaid. Este sitio usa la 11.12.2. La sintaxis añadida después de la versión 10 se dibuja aquí y falla allí, y esa es la explicación habitual de «funciona en el visor pero no en nuestro GitLab». En GitLab autogestionado hay una tercera trampa: si la cabecera Cross-Origin-Resource-Policy está puesta a same-site o same-origin, los diagramas de Mermaid fallan en silencio, sin error y sin diagrama.
.mmd frente a .mermaid frente a .md
.mmd y .mermaid son lo mismo. Ambos contienen únicamente código Mermaid, y todas las herramientas que conozco que aceptan una aceptan la otra. .mmd es la más corta y la más habitual de las dos; la herramienta oficial de línea de comandos la usa por defecto. Elige una y sé coherente dentro de un proyecto: la decisión no tiene ninguna consecuencia técnica.
.md es distinto en naturaleza. Un archivo Markdown es un documento que puede contener un diagrama de Mermaid, envuelto en un bloque que empieza con tres acentos graves seguidos de la palabra mermaid. El diagrama es un fragmento dentro de un texto mayor.
Esa diferencia es, con mucho, la razón más común de que un archivo no se dibuje, y funciona en las dos direcciones. Pega el contenido de un .md en un visor de Mermaid y falla, porque la línea del delimitador no es sintaxis de Mermaid. Guarda un diagrama Mermaid suelto en un .md sin delimitadores y GitHub lo enseñará como un párrafo de texto. La regla es simple: un .mmd tiene que empezar por una palabra clave de diagrama, y un .md tiene que llevar el diagrama dentro de un bloque delimitado.
Este visor acepta .mmd, .mermaid, .md y .txt, pero trata todo lo que lee como Mermaid en bruto. Si sueltas un Markdown con prosa alrededor del diagrama, quita antes todo lo que no sea el diagrama.
No se dibuja: qué falla en realidad
Los mensajes de error de Mermaid son precisos pero poco amables. El truco útil es leer el final del mensaje: después de «got», Mermaid nombra el token con el que se atragantó, y ese token identifica el problema mucho mejor que el número de línea. He reproducido todos los casos de abajo con mermaid 11.12.2: la versión rota falla de verdad y la corregida se dibuja de verdad.
Lo que ves
No diagram type detected matching given configuration for text: ```mermaid
Por qué
Has copiado el diagrama desde un archivo Markdown o desde un chat y te has traído el delimitador. Los tres acentos graves son Markdown, no Mermaid, así que el analizador nunca llega al diagrama.
Solución
Borra la línea de apertura ```mermaid y la de cierre ```. El archivo tiene que empezar por la palabra clave del diagrama.
```mermaid
flowchart TD
A[Inicio] --> B[Fin]
```flowchart TD
A[Inicio] --> B[Fin]Lo que ves
Parse error, el mensaje termina en: got 'PS'
El error termina en: got 'PS'
Por qué
Un paréntesis de apertura dentro de la etiqueta de un nodo. En Mermaid los paréntesis son sintaxis de forma — A(texto) es un nodo redondeado —, así que un ( suelto entre corchetes se lee como el principio de una forma.
Solución
Entrecomilla la etiqueta. Todo lo que va entre comillas dobles se trata como texto, corchetes incluidos.
flowchart TD
A[Llamar a cobrar(pedido)] --> B[Fin]flowchart TD
A["Llamar a cobrar(pedido)"] --> B[Fin]Lo que ves
Parse error en la línea donde nombraste un nodo
Por qué
El identificador de un nodo lleva espacios. En español es el error más fácil de cometer, porque los nombres naturales son sintagmas: «servicio de autenticación», «base de datos». El identificador es el token anterior a la flecha y el espacio lo corta, así que queda una palabra suelta que no encaja en ningún sitio.
Solución
Dale al nodo un identificador de una sola palabra y pon el texto legible en la etiqueta. Los acentos y la ñ sí valen dentro del identificador; lo único que rompe es el espacio.
flowchart TD
servidor de auth --> base de datosflowchart TD
auth[Servidor de autenticación] --> db[Base de datos]Lo que ves
Parse error, el mensaje termina en: got 'STR'
El error termina en: got 'STR'
Por qué
Comillas dobles dentro de la etiqueta de un nodo. El analizador las toma como el principio de una cadena entrecomillada y luego encuentra el corchete de la etiqueta donde esperaba la comilla de cierre.
Solución
Envuelve toda la etiqueta en comillas dobles y usa comillas simples o angulares dentro, o escribe la comilla como la entidad HTML #quot;.
flowchart TD
A[Dijo "hola"] --> B[Fin]flowchart TD
A["Dijo 'hola'"] --> B[Fin]Lo que ves
Parse error, el mensaje termina en: got 'end'
El error termina en: got 'end'
Por qué
Has usado end como identificador de nodo. En minúsculas, end cierra un subgrafo, así que el analizador ve un fin de bloque donde esperaba un nodo. Pasa más de lo que parece: siguiendo ejemplos en inglés uno acaba llamando end al último nodo aunque el resto esté en español.
Solución
Ponlo en mayúscula o dale otro identificador y mete la palabra en la etiqueta. `Fin` no da ningún problema.
flowchart TD
A[Inicio] --> endflowchart TD
A[Inicio] --> Fin[Terminado]Lo que ves
No diagram type detected matching given configuration for text: sequencediagram
Por qué
La palabra clave del diagrama está mal escrita, o con las mayúsculas equivocadas. Las palabras clave de Mermaid distinguen mayúsculas: sequenceDiagram funciona, sequencediagram no. Lo mismo vale para stateDiagram-v2 y erDiagram.
Solución
Corrige las mayúsculas. Ten en cuenta que graph sigue admitiéndose como alias antiguo de flowchart, así que esa sintaxis vieja no es tu problema.
sequencediagram
Cliente->>API: HolasequenceDiagram
Cliente->>API: HolaLo que ves
Parse error en una etiqueta de arista entre barras
Por qué
Paréntesis dentro de la etiqueta de una arista. La etiqueta |...| tiene la misma restricción que la de un nodo: los corchetes y paréntesis son sintaxis, no texto.
Solución
Entrecomilla la etiqueta de la arista.
flowchart TD
A -->|sí (siempre)| Bflowchart TD
A -->|"sí (siempre)"| BLo que ves
Se dibuja, pero un diagrama ER tiene entidades que no escribiste
Por qué
Una etiqueta de relación con espacios y sin comillas. Es la trampa que más castiga al español, porque nuestros verbos de relación llevan preposición: «pertenece a», «aparece en». Mermaid no da error: corta la etiqueta en el primer espacio y convierte cada palabra restante en una entidad vacía.
Solución
Entrecomilla toda etiqueta de relación que lleve un espacio. En español, prácticamente todas.
erDiagram
CLIENTE ||--o{ PEDIDO : pertenece aerDiagram
CLIENTE ||--o{ PEDIDO : "pertenece a"Lo que ves
Parse error en un diagrama ER, el mensaje termina en: got 'NEWLINE'
El error termina en: got 'NEWLINE'
Por qué
Una relación sin etiqueta. A diferencia de una arista de diagrama de flujo, una relación ER exige los dos puntos y un sintagma verbal: no es opcional, y omitirlo termina la línea antes de tiempo.
Solución
Añade los dos puntos y una etiqueta.
erDiagram
CLIENTE ||--o{ PEDIDOerDiagram
CLIENTE ||--o{ PEDIDO : "realiza"Lo que ves
Parse error señalado en la última línea del diagrama
Por qué
Un bloque abierto y nunca cerrado: alt, opt, loop, par y subgraph necesitan su end. Mermaid informa del fallo en el punto en que se le acaba la entrada, así que el número de línea apunta al final del archivo y no al bloque sin cerrar.
Solución
Cuenta los bloques que abres y los end que escribes. Si el error señala la última línea, casi siempre es esto.
sequenceDiagram
Cliente->>API: Petición
alt Todo bien
API-->>Cliente: OKsequenceDiagram
Cliente->>API: Petición
alt Todo bien
API-->>Cliente: OK
endLo que ves
Lexical error on line 1. Unrecognized text.
Por qué
Una dirección no válida detrás de la palabra clave del diagrama. Los diagramas de flujo aceptan TB, TD, BT, LR y RL, y nada más; una errata aquí falla en el análisis léxico, antes de leer ningún nodo.
Solución
Usa una de las cinco direcciones válidas. Con TD y LR se cubre casi todo.
flowchart XY
A --> Bflowchart TD
A --> BLo que ves
Aquí se dibuja pero en GitLab, Confluence o una herramienta antigua no
Por qué
Una diferencia de versión. Este visor usa Mermaid 11.12.2; GitLab.com documenta la versión 10, y los wikis autoalojados suelen ir años por detrás. La sintaxis introducida después de la versión de la otra herramienta se analiza aquí y falla allí.
Solución
Pregúntale a la otra herramienta qué versión usa. Escribir la palabra info como único contenido de un diagrama hace que Mermaid dibuje su propio número de versión, y es más rápido que leer notas de publicación.
infoHay un problema más que en español conviene tener presente: la codificación. Esta página y el editor leen el archivo como UTF-8, y quitan la marca BOM si la lleva, así que un archivo guardado desde el Bloc de notas de Windows como «UTF-8 con BOM» se abre sin problemas. Pero un archivo guardado en ISO-8859-1 o Windows-1252, que es lo que todavía sale de algunas herramientas antiguas, llegará con las tildes y las eñes convertidas en símbolos raros. Si las etiquetas se ven con caracteres extraños donde debería haber acentos, vuelve a guardar el archivo como UTF-8 desde tu editor.
Y una última cosa que no produce ningún error: en GitLab autogestionado, una cabecera Cross-Origin-Resource-Policy puesta a same-site o same-origin hace que los diagramas de Mermaid fallen en silencio. Ni mensaje, ni diagrama, nada en la página. Si un diagrama se dibuja en todas partes menos en una instancia autoalojada, mira ahí.
Convertir a PNG, SVG o PDF
Abre el archivo en el editor y usa los botones de exportación. El SVG mantiene el diagrama como texto vectorial, así que se mantiene nítido a cualquier tamaño y las etiquetas se pueden seleccionar y buscar: es la opción correcta para documentación y para cualquier cosa que puedas querer reexportar más adelante. El PNG es un mapa de bits, exportado aquí a dos o tres veces el tamaño de pantalla para que aguante en pantallas de alta densidad; úsalo donde no se acepte SVG, que en la práctica significa la mayoría de los clientes de chat y algunos wikis.
No hay botón de PDF, y prefiero decirlo antes que disimularlo. La vía práctica es exportar SVG y o bien colocarlo en el documento que ya estás escribiendo, o imprimir esa página a PDF desde el navegador. Un SVG vectorial colocado en un PDF sigue siendo vectorial.
Para cualquier cosa repetible — un paso de compilación, un lote de archivos, un hook de pre-commit — está el renderizador oficial de línea de comandos, @mermaid-js/mermaid-cli, que toma el mismo archivo .mmd y escribe la imagen directamente sin navegador.
Preguntas frecuentes
¿Cómo abro un archivo .mmd online?
¿Qué programa abre un archivo .mmd?
¿Un archivo .mmd es lo mismo que uno .mermaid?
¿Por qué mi archivo .mmd no se dibuja en GitHub?
¿Puedo abrir un .mmd sin instalar nada?
Las tildes y las eñes se ven como símbolos raros
Aquí funciona pero en nuestro wiki no. ¿Por qué?
Tipos de diagrama que puedes abrir aquí
Escrito por Dominik Malsch · Última actualización: