Mermaid ASCII: renderizado de diagramas Mermaid en la terminal

 (github.com/lukilabs)
16 puntos por GN⁺ 2026-01-30 | 1 comentarios | Compartir por WhatsApp
  • beautiful-mermaid es una herramienta ultrarrápida basada en TypeScript para renderizar diagramas Mermaid como SVG o arte ASCII
  • Soporta 5 tipos de diagramas (Flowchart, State, Sequence, Class, ER) y funciona tanto en la terminal como en el navegador
  • Con 15 temas integrados y compatibilidad con Shiki, permite aplicar directamente temas de VS Code
  • El modo Mono ofrece una representación visual consistente usando solo dos colores, y las propiedades personalizadas de CSS permiten cambiar de tema en tiempo real
  • Destaca como una herramienta ligera y sin dependencias para visualizar flujos de datos y estructuras de sistema en entornos de programación asistida por IA

Resumen general

  • beautiful-mermaid es una herramienta para renderizar diagramas Mermaid como SVG o texto ASCII/Unicode
    • Funciona sin dependencia del DOM y ofrece renderizado ultrarrápido (más de 100 diagramas en menos de 500 ms)
    • Fue desarrollada por el equipo de Craft para Craft Agents
  • Hace un port a TypeScript de Mermaid-ascii (proyecto basado en Go) y amplía sus funciones
    • Añade soporte para diagramas Sequence, Class y ER
    • Incluye caracteres de caja Unicode y opciones de configuración de espaciado y padding

Funciones principales

  • Tipos de diagramas compatibles: Flowchart, State, Sequence, Class, ER
  • Formatos de salida: SVG (para interfaces enriquecidas), ASCII/Unicode (para terminal)
  • Sistema de temas
    • Incluye 15 temas integrados (tokyo-night, dracula, nord, github-dark, etc.)
    • Modo Mono: deriva automáticamente toda la paleta a partir de solo dos colores, fondo (bg) y primer plano (fg)
    • Modo Enriched: permite definir colores opcionales como accent, muted, surface, border, etc.
    • Soporta cambio en tiempo real basado en propiedades personalizadas de CSS
  • Integración con Shiki
    • Mapea automáticamente los colores de temas de VS Code a los colores del diagrama
    • La función fromShikiTheme() puede extraer bg, fg, accent, etc.

Instalación y uso

  • Comando de instalación
    • npm install beautiful-mermaid o bun add beautiful-mermaid, pnpm add beautiful-mermaid
  • Ejemplo de renderizado SVG 
    import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid(`graph TD; A-->B;`)
  • Ejemplo de renderizado ASCII 
    import { renderMermaidAscii } from 'beautiful-mermaid'
const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)
  • Uso en navegador
    • Se puede cargar directamente mediante la etiqueta <script> usando un CDN (unpkg, jsDelivr)
    • Se puede acceder a renderMermaid, renderMermaidAscii, THEMES, etc. desde el objeto global beautifulMermaid

Salida ASCII y opciones

  • Soporta modo Unicode (predeterminado) y modo ASCII puro
  • Opciones disponibles
    • useAscii: si se usa ASCII
    • paddingX, paddingY: espaciado entre nodos
    • boxBorderPadding: relleno interno del nodo
  • Ejemplo de salida 
    ┌───┐     ┌───┐
│ A │────►│ B │
└───┘     └───┘

Resumen de la API

  • renderMermaid(text, options?): renderiza un diagrama Mermaid como SVG
    • Opciones: bg, fg, accent, muted, surface, border, font, transparent
  • renderMermaidAscii(text, options?): renderiza como texto ASCII/Unicode
  • fromShikiTheme(theme): extrae colores desde un tema de Shiki
  • THEMES: objeto con 15 temas integrados
  • DEFAULTS: colores predeterminados (#FFFFFF, #27272A)

Licencia y autoría

  • Licencia MIT
  • Creado por el equipo de Craft
  • Motor ASCII basado en mermaid-ascii de Alexander Grooff

Importancia técnica

  • En entornos de asistentes de código con IA, permite visualizar al instante diagramas dentro de la terminal o una interfaz de chat
  • Gracias a su arquitectura ligera, rápida y sin dependencias, también resulta muy útil en herramientas CLI o entornos de servidor
  • Su capacidad de expansión de temas y compatibilidad mejora la experiencia de desarrollo

Lecturas relacionadas

1 comentarios

 
GN⁺ 2026-01-30
Opiniones en Hacker News

  • El proyecto basado en la librería de Go mermaid-ascii, creada por Alexander Grooff, está realmente genial
    Aunque encontré un bug donde no se renderiza la arista "start"
    Hice las pruebas en agents.craft.do/mermaid

  • No entiendo muy bien por qué los diagramas ASCII están volviendo a llamar la atención últimamente
    Mermaid y PlantUML ya son basados en texto, y la mayoría de los usuarios quieren diagramas estándar que se vean bien para las personas, no para las máquinas
    ASCII está limitado a caracteres imprimibles, así que tiene menos expresividad y también es difícil de estandarizar

    • Depende del contexto. Por ejemplo, en entornos donde no se puede renderizar Mermaid, como un README o la salida de una CLI, ASCII es la mejor opción en términos de legibilidad
    • Puedes poner diagramas ASCII dentro de comentarios de código. También se ven bien en herramientas basadas en terminal como Claude Code
    • Más que decir “ASCII no sirve”, en flujos de trabajo centrados en texto (por ejemplo, Org Mode o gestión de repositorios Git) puede ser muy útil
      Porque no hace falta lidiar con archivos de imagen ni configuraciones complejas como Git LFS
    • Una ventaja es que no necesita renderizador. Se puede leer directamente en forma “renderizada” dentro de documentos Markdown o código fuente
    • Como muchos desarrolladores y agentes de código trabajan principalmente en entornos Markdown y CLI, este enfoque ASCII resulta natural

  • A mí me gustan muchísimo los diagramas ASCII
    Me encanta que se vean igual de bien tanto en la terminal con cat como renderizados en un sitio web
    Con una buena fuente monoespaciada, también se ven limpios visualmente
    También recomiendo la app para crear diagramas ASCII Monodraw

    • ^Unicode
    • Me gusta especialmente que puedes poner diagramas al inicio del código fuente

  • El renderizador ASCII de Mermaid en realidad fue traído del proyecto AlexanderGrooff/mermaid-ascii
    Este proyecto lo convirtió a TypeScript y le agregó sus propios temas

    • En realidad, probablemente habría bastado con empaquetar mermaid-ascii en WASM
      El algoritmo principal es casi una conversión 1:1, así que Claude probablemente habría tardado menos de una hora en portarlo a TS
      Se pueden comparar el código en Go y el código en TS
    • Gracias por dar el crédito
    • Como está hecho en Go, ni siquiera hace falta un chiste sobre gestión de paquetes. Pienso integrarlo en mi depurador
    • Alguien señaló que quizá una IA copió todo el proyecto y solo le cambió el nombre
    • Ya corregí el enlace al original. Parece que quien lo envió lo hizo de buena fe

  • Mermaid está recibiendo mucha atención, pero Kroki(kroki.io) soporta una variedad mucho mayor de formatos de diagramas
    Incluye casi todos los diagramas basados en texto, como BlockDiag, BPMN, C4, D2, DBML, Excalidraw, GraphViz y más
    Mi editor Markdown, KeenWrite(keenwrite.com), integra Kroki como servicio, así que cuando se añade un formato nuevo, queda disponible automáticamente
    Mermaid usa <foreignObject>, por lo que la mayoría de las librerías tienen problemas para renderizarlo

    • Comparar MermaidJS con Kroki es un poco como comparar PDF.js con Adobe Acrobat
      MermaidJS corre rápido y de forma local dentro de una página web, mientras que Kroki depende de un servicio externo
      Si no necesitas diagramas complejos, Mermaid es una opción más simple
    • Hace tiempo quise renderizar DAG de NetworkX en ASCII y por eso hice una herramienta llamada phart
      En los ejemplos del README hay varias salidas, incluyendo un grafo de ajedrez
    • Al principio pensé que el diseño de Kroki no me gustaba porque tenía demasiadas sombras y distorsión de fuentes, pero después me di cuenta de que había sido un malentendido
      Aun así, siento que el estilo predeterminado de Mermaid es más limpio
      Por cierto, KeenWrite se ve bastante bien

  • También existe Diagon, una herramienta para convertir texto en diagramas ASCII
    Yo también armé una lista de herramientas de texto→diagrama, aunque no hay muchas que conviertan texto→ASCII

    • Le agradecieron por la buena lista

  • Para ejecutar la demo en vivo, parece que hay que descargar una plataforma de agentes de IA
    Es una lástima no poder probarlo directamente sin instalar nada

    • Estaría bueno que los desarrolladores hicieran una demo solo cliente basada en GitHub Pages
      Por la estructura del proyecto, parece totalmente posible

  • Existe una función llamada “Subgraph Direction Override”, con la que se puede configurar una dirección distinta para los subgrafos
    Con eso se puede imitar un diagrama de carriles de natación que Mermaid no soportaba

  • Selkie, que hice yo, es un proyecto experimental que implementa por completo el parser y el renderizador de Mermaid en Rust
    Lo hice para probar hasta dónde se podía llegar con Claude Code, y el resultado fue sorprendente
    Se puede ejecutar directamente en el Playground
    Si soporta la terminal Kitty, también puede mostrar los diagramas directamente en la terminal
    Pronto voy a escribir una entrada de blog con todo el proceso

  • Este proyecto está realmente genial, y la sinergia con Claude Code también impresiona
    Yo hice un proyecto parecido, pero en vez de ASCII se enfoca en la exploración interactiva de código
    Lo diseñé para ayudar a la comprensión humana, usé D2 y también estoy preparando soporte para Mermaid
    Me interesa escuchar opiniones sobre si la interactividad para personas tiene más valor, o si lo importante es el contexto para agentes
    Enlace del proyecto