Cómo incrustar diagramas Mermaid
Algunas herramientas dibujan Mermaid por ti a partir de texto plano; otras necesitan una imagen exportada. Aquí tienes dónde se renderiza de forma nativa, cómo incrustarlo en cada plataforma y la alternativa cuando una herramienta no puede.
- 01
Crea el diagrama
Abre el editor, escribe o pega tu Mermaid y confirma que se renderiza como quieres.
- 02
Copia el código fuente o exporta una imagen
Para las plataformas que renderizan Mermaid de forma nativa, copia el bloque Markdown delimitado ```mermaid. Para todo lo demás, exporta un SVG o PNG.
- 03
Pégalo donde corresponde
Pega el bloque Mermaid en una plataforma nativa, o coloca la imagen exportada en un documento, una diapositiva o un correo. Conserva el código fuente en tu repositorio para que siga siendo editable.
Dónde se renderiza Mermaid, plataforma por plataforma
| Plataforma | Soporte de Mermaid | Cómo incrustar |
|---|---|---|
| GitHub | Nativo | Pega un bloque delimitado ```mermaid en cualquier README, archivo Markdown, issue, pull request, discusión o wiki. GitHub lo dibuja automáticamente. |
| GitLab | Nativo | El mismo bloque delimitado ```mermaid funciona en Markdown, issues y merge requests en GitLab.com y en instancias autogestionadas. |
| Obsidian | Nativo | Escribe un bloque de código ```mermaid en cualquier nota; Obsidian lo renderiza en los modos de lectura y vista previa en vivo, sin necesidad de plugin. |
| Notion | Nativo (bloque de código) | Inserta un bloque /code, establece su lenguaje en "Mermaid", pega el código fuente y luego usa la vista Preview / Split del bloque para mostrar el diagrama. |
| Confluence | Requiere una app | Confluence no incluye Mermaid de forma integrada. Instala una app del Marketplace (por ejemplo, una macro de Mermaid) y pega el código fuente en ella, o incrusta un SVG/PNG exportado. |
| Tu propio sitio web | Nativo (añade el script) | Coloca el código fuente en una etiqueta "pre" con la clase "mermaid" y carga mermaid.js desde un CDN; consulta el fragmento más abajo. O incrusta un SVG exportado para cero JavaScript. |
| Slack, Google Docs, correo, PDF | Exportar una imagen | Estos no renderizan Mermaid. Exporta un SVG (nítido a cualquier tamaño) o un PNG desde el editor y pega esa imagen. |
Las funciones de las plataformas cambian: verifícalo en tu propia cuenta, especialmente para las vistas previas de Notion y las apps de Confluence. "Nativo" significa que el diagrama se renderiza desde el código fuente sin subir ninguna imagen.
Incrustar en tu propio sitio web
Pega el código fuente de Mermaid en un elemento "pre" con la clase "mermaid" y carga el renderizador desde un CDN. Esta es la incrustación oficial con ESM; cópiala tal cual:
<pre class="mermaid">
flowchart TD
A[Start] --> B{OK?}
B -->|Yes| C[Ship]
B -->|No| A
</pre>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>Fija una versión mayor (aquí mermaid@11) para que una versión futura no pueda cambiar tus diagramas de forma inesperada. Para una página estática sin JavaScript, exporta un SVG desde el editor y refiérelo como una imagen en su lugar.
README de GitHub, paso a paso
GitHub es el destino más común. Para el tutorial completo, incluido por qué un bloque a veces se muestra como código en lugar de como diagrama, consulta cómo incrustar un diagrama Mermaid en un README de GitHub.
Crea primero un diagrama: abre el editor de Mermaid, ejemplos listos para usar.
Preguntas frecuentes
¿Qué plataformas renderizan Mermaid sin un plugin?
GitHub, GitLab y Obsidian renderizan los bloques delimitados ```mermaid de forma nativa. Notion lo renderiza dentro de un bloque de código configurado con el lenguaje Mermaid mediante su vista previa. La mayoría de las demás herramientas (Slack, Google Docs, correo) necesitan en su lugar una imagen SVG o PNG exportada.
¿Cómo incrusto un diagrama Mermaid en Notion?
Añade un bloque de código (escribe /code), cambia su lenguaje a "Mermaid" y pega el código fuente de tu diagrama. Notion muestra un conmutador Preview / Split en el bloque que renderiza el diagrama. Para una copia estática, exporta una imagen desde el editor e incrústala en su lugar.
¿Cómo muestro un diagrama Mermaid en mi propio sitio web?
Coloca el código fuente dentro de un elemento "pre" con la clase "mermaid" y carga mermaid.js desde un CDN con mermaid.initialize({ startOnLoad: true }). El fragmento de esta página es un ejemplo completo y funcional. Si prefieres no incluir JavaScript, exporta un SVG y úsalo como imagen.
¿Debo incrustar el código fuente o una imagen exportada?
Donde la plataforma renderiza Mermaid (GitHub, GitLab, Obsidian, tu propio sitio), incrusta el código fuente: sigue siendo editable y comparable en el control de versiones. Donde no, exporta un SVG o PNG. El SVG escala sin difuminarse; el PNG es ideal para diapositivas.
¿Confluence admite Mermaid?
No de forma predeterminada. Necesitas una app del Marketplace que añada una macro de Mermaid, o puedes pegar una imagen SVG/PNG exportada. Consulta con el administrador de tu Confluence sobre la app que tienes permitido instalar.