Diagramas en Markdown: ASCII, Mermaid y código con el tema del blog

Un diagrama en una nota es un dibujo hecho con texto: cajas, flechas y líneas que, puestas en su sitio, explican una idea mejor que un párrafo. En este blog hay tres formas de escribirlos dentro de un bloque de código, y el blog las convierte en SVG cuando compila: se ven nítidas en cualquier pantalla y con los colores del tema. Es el mismo gesto que explicamos para los medios embebidos, pero con esquemas en lugar de vídeos.

Tres formas de dibujar

• ASCII: cajas y flechas dibujadas con caracteres, para esquemas pequeños y claros.
• Mermaid: un lenguaje de diagramas (flujo, secuencia, Gantt, pastel…) que se describe con texto.
• Código: fragmentos de js, bash, python… con resaltado, tipografía monoespaciada y botón de copiar.

Las tres salen como una figura con el mismo marco y el mismo pie, así que se pueden mezclar en un artículo sin que el diseño se rompa.

Diagramas ASCII

Antes de existir como imagen, un esquema era texto: guiones para las líneas, barras para los lados y signos de suma para las esquinas. Sigue siendo la forma más rápida de anotar un flujo en Obsidian, porque no hay que salir del teclado. Se abre el bloque con ascii (o diagram) y dentro va el dibujo tal cual:

```ascii caption="Flujo de publicación"
+--------+     +--------+
| Astro  |---->| Post   |
+--------+     +--------+
```

ASCII

Diagramas Mermaid

Mermaid describe el diagrama con texto y lo dibuja por ti, así que sirve para esquemas que en ASCII serían un jeroglífico: flujos ramificados, diagramas de secuencia, de clases, de estados, Gantt o de pastel. Se abre el bloque con mermaid y se escribe su sintaxis:

```mermaid caption="El flujo de este mismo artículo."
flowchart TD
  A[Escribir] --> B{¿Pasa el gate?}
  B -->|sí| C[Publicar]
  B -->|no| D[Corregir]
```

Mermaid

Mermaid necesita un navegador para medir el texto, así que no se dibuja durante el build: se renderiza en tu máquina y el SVG queda guardado en el repositorio. Antes de publicar un diagrama nuevo hay que dibujarlo una vez:

npm run diagrams:render

Si un bloque mermaid se queda sin dibujar, la publicación se corta con un aviso que lo dice. No hay que escribir nunca el <svg> a mano.

Bloques de código

Cualquier otro lenguaje se sigue tratando como código, ahora con un marco propio: superficie oscura y monoespaciada, y un botón Copiar que aparece al pasar el ratón por encima. El resaltado lo pone el propio build, así que no hay que hacer nada: basta con abrir el bloque con el lenguaje correcto.

```js
const diagrama = (texto) => texto.trim();
```

const diagrama = (texto) => texto.trim();

Cómo se pinta

El color de un diagrama no está fijado: hereda el del tema. En modo claro se dibuja en oscuro y en modo oscuro se aclara, sin que tengas que hacer nada —y lo mismo con cualquiera de los temas del blog—. La geometría también se adapta: la imagen se escala al ancho de la columna en vez de quedarse a un tamaño fijo, y si un diagrama es muy ancho, la figura deja desplazarlo de lado. Todo lo que necesitas saber para que un esquema se vea bien es que el dibujo ASCII se escriba alineado y que el bloque de Mermaid se dibuje antes de publicar.

Qué conviene no dibujar

Los esquemas brillan cuando la idea es una y clara. Con muchas cajas y cruces, el resultado se vuelve difícil de seguir; para eso suele salir mejor apoyarse en el texto y reservar el dibujo para lo central. La misma lógica que seguimos al elegir cuándo incrustar un reproductor o un vídeo en una nota.

Con esto tienes el sistema completo: tres bloques, un pie opcional y un botón de copiar. El resto es tu imaginación con los caracteres.