Mermaid ASCII: renderização de diagramas Mermaid no terminal

 (github.com/lukilabs)
16 pontos por GN⁺ 2026-01-30 | 1 comentários | Compartilhar no WhatsApp
  • beautiful-mermaid é uma ferramenta ultrarrápida baseada em TypeScript para renderizar diagramas Mermaid em SVG ou arte ASCII
  • Suporta 5 tipos de diagramas (Flowchart, State, Sequence, Class, ER) e funciona tanto no terminal quanto no navegador
  • Com 15 temas embutidos e compatibilidade com Shiki, é possível aplicar diretamente temas do VS Code
  • O modo Mono fornece uma apresentação visual consistente usando apenas duas cores, e também há suporte a propriedades personalizadas de CSS para troca de tema em tempo real
  • Destaca-se como uma ferramenta leve e sem dependências para visualizar fluxos de dados e estruturas de sistemas em ambientes de programação assistida por IA

Visão geral

  • beautiful-mermaid é uma ferramenta para renderizar diagramas Mermaid em SVG ou texto ASCII/Unicode
    • Funciona sem dependência de DOM e oferece renderização ultrarrápida (mais de 100 diagramas em menos de 500 ms)
    • Desenvolvida pela equipe Craft para o Craft Agents
  • Faz o port de mermaid-ascii (projeto baseado em Go) para TypeScript e expande suas funcionalidades
    • Adiciona suporte a diagramas Sequence, Class e ER
    • Inclui caracteres de caixa Unicode e recursos de configuração de espaçamento e padding

Principais recursos

  • Tipos de diagramas suportados: Flowchart, State, Sequence, Class, ER
  • Formatos de saída: SVG (para UIs ricas), ASCII/Unicode (para terminal)
  • Sistema de temas
    • Fornece 15 temas embutidos (tokyo-night, dracula, nord, github-dark etc.)
    • Modo Mono: deriva automaticamente toda a paleta a partir de apenas duas cores, fundo (bg) e primeiro plano (fg)
    • Modo Enriched: permite definir cores opcionais como accent, muted, surface, border etc.
    • Suporte a troca em tempo real baseada em propriedades personalizadas de CSS
  • Integração com Shiki
    • Mapeia automaticamente as cores dos temas do VS Code para as cores dos diagramas
    • A função fromShikiTheme() pode extrair bg, fg, accent etc.

Instalação e uso

  • Comandos de instalação
    • npm install beautiful-mermaid ou bun add beautiful-mermaid, pnpm add beautiful-mermaid
  • Exemplo de renderização SVG 
    import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid(`graph TD; A-->B;`)
  • Exemplo de renderização ASCII 
    import { renderMermaidAscii } from 'beautiful-mermaid'
const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)
  • Uso no navegador
    • Pode ser carregado diretamente por uma tag <script> via CDN (unpkg, jsDelivr)
    • É possível acessar renderMermaid, renderMermaidAscii, THEMES etc. pelo objeto global beautifulMermaid

Saída ASCII e opções

  • Suporte a modo Unicode (padrão) e modo ASCII puro
  • Itens de opção
    • useAscii: se usa ASCII
    • paddingX, paddingY: espaçamento entre nós
    • boxBorderPadding: margem interna do nó
  • Exemplo de saída 
    ┌───┐     ┌───┐
│ A │────►│ B │
└───┘     └───┘

Resumo da API

  • renderMermaid(text, options?): renderiza um diagrama Mermaid em SVG
    • Opções: bg, fg, accent, muted, surface, border, font, transparent
  • renderMermaidAscii(text, options?): renderiza em texto ASCII/Unicode
  • fromShikiTheme(theme): extrai cores de um tema Shiki
  • THEMES: objeto com 15 temas embutidos
  • DEFAULTS: cores padrão (#FFFFFF, #27272A)

Licença e autoria

  • Licença MIT
  • Criado pela equipe Craft
  • Motor ASCII baseado em mermaid-ascii, de Alexander Grooff

Significado técnico

  • Em ambientes de assistentes de codificação com IA, permite visualizar imediatamente diagramas dentro do terminal ou de interfaces de chat
  • Com sua estrutura leve, rápida e sem dependências, também é altamente útil em ferramentas de CLI e ambientes de servidor
  • Melhora a experiência do desenvolvedor por meio de expansibilidade de temas e compatibilidade

Leituras relacionadas

1 comentários

 
GN⁺ 2026-01-30
Comentários do Hacker News

  • O projeto baseado na biblioteca Go mermaid-ascii, criada por Alexander Grooff, é realmente muito legal
    Mas encontrei um bug em que a aresta "start" não é renderizada
    Os testes foram feitos em agents.craft.do/mermaid

  • Não entendo muito bem por que os diagramas ASCII estão voltando a chamar atenção ultimamente
    Mermaid e PlantUML já são baseados em texto, e a maioria dos usuários quer diagramas padrão que sejam agradáveis para humanos, não para máquinas
    ASCII é limitado a caracteres imprimíveis, então tem menos expressividade e também é mais difícil de padronizar

    • Depende do contexto. Por exemplo, em ambientes onde não é possível renderizar Mermaid, como README ou saída de CLI, ASCII é a melhor escolha em termos de legibilidade
    • Dá para colocar diagramas ASCII dentro de comentários de código. Eles também ficam bons em ferramentas baseadas em terminal como Claude Code
    • Em vez de dizer que “ASCII é inútil”, em workflows centrados em texto (por exemplo, Org Mode, gerenciamento de repositórios Git), ele pode ser bastante útil
      Porque não exige gerenciamento de arquivos de imagem nem configurações complexas como Git LFS
    • O fato de não precisar de renderizador é uma vantagem. Dá para ler diretamente na forma já “renderizada” dentro de documentos Markdown ou código-fonte
    • Como muitos desenvolvedores e agentes de programação usam principalmente Markdown e ambientes de CLI, essa abordagem em ASCII parece natural

  • Eu gosto muito de diagramas ASCII
    O charme é que eles ficam igualmente legais tanto vendo com cat no terminal quanto renderizados em um site
    Com uma boa fonte monospaced, o visual também fica limpo
    Também recomendo o app de criação de diagramas ASCII Monodraw

    • ^Unicode
    • Gosto especialmente do fato de ser possível colocar diagramas no topo do código-fonte

  • O renderizador Mermaid ASCII de fato foi trazido do projeto AlexanderGrooff/mermaid-ascii
    Este projeto o converteu para TypeScript e adicionou um tema próprio

    • Na verdade, talvez desse para simplesmente empacotar mermaid-ascii em WASM
      Como o algoritmo principal foi convertido quase 1:1, parece que o Claude teria levado menos de uma hora para portar para TS
      Dá para comparar o código Go com o código TS
    • Obrigado pelo crédito
    • Como é baseado em Go, nem precisa fazer piada sobre gerenciamento de pacotes. Pretendo integrar ao meu depurador
    • Alguém apontou que talvez a IA tenha copiado o projeto inteiro e só trocado o nome
    • O link original foi corrigido. Parece que quem enviou o post fez isso de boa-fé

  • Mermaid está ganhando atenção, mas Kroki(kroki.io) suporta uma variedade muito maior de formatos de diagrama
    Inclui praticamente todos os diagramas baseados em texto, como BlockDiag, BPMN, C4, D2, DBML, Excalidraw e GraphViz
    Meu editor Markdown, KeenWrite(keenwrite.com), integra o Kroki como serviço, então novos formatos passam a ficar disponíveis automaticamente quando são adicionados
    Como o Mermaid usa <foreignObject>, a renderização é difícil na maioria das bibliotecas

    • Comparar MermaidJS com Kroki é parecido com comparar PDF.js e Adobe Acrobat
      MermaidJS roda rápido e localmente dentro da página web, enquanto o Kroki depende de um serviço externo
      Se você não precisa de diagramas complexos, Mermaid é a escolha mais simples
    • No passado, criei uma ferramenta chamada phart para renderizar DAGs do NetworkX em ASCII
      Há vários exemplos de saída, incluindo grafos de xadrez, nos exemplos do README
    • No começo achei que o design do Kroki era ruim por causa de muito sombreamento e distorção de fontes, mas depois percebi que era um engano
      Ainda assim, acho o estilo padrão do Mermaid mais limpo
      Aliás, o KeenWrite parece muito bom

  • Também existe a ferramenta Diagon, que converte texto em diagramas ASCII
    Eu também organizei uma lista de ferramentas de texto→diagrama, mas não há tantas ferramentas de conversão de texto→ASCII

    • A pessoa agradeceu, dizendo que é uma ótima lista

  • Para rodar a demo ao vivo, parece que é preciso baixar uma plataforma de agentes de IA
    É uma pena não dar para testar diretamente sem instalar nada

    • Seria bom se os desenvolvedores criassem uma demo somente cliente baseada em GitHub Pages
      Pela estrutura do projeto, isso parece totalmente viável

  • Existe o recurso “Subgraph Direction Override”, que permite definir uma direção diferente para subgrafos
    Com isso, dá para imitar diagramas de swim lane que o Mermaid não suportava

  • O Selkie, que eu criei, é um projeto experimental que implementa completamente o parser e o renderizador do Mermaid em Rust
    Servia para testar até onde dava para chegar com o Claude Code, e o resultado foi surpreendente
    Dá para executar direto no Playground
    Se houver suporte ao terminal Kitty, também é possível exibir os diagramas diretamente no terminal
    Em breve vou escrever um post no blog detalhando todo o processo

  • Este projeto é realmente muito legal, e a sinergia com Claude Code também impressiona
    Eu fiz um projeto parecido, mas foquei em exploração interativa de código em vez de ASCII
    Foi projetado para ajudar na compreensão humana, usa D2, e o suporte a Mermaid também está a caminho
    Gostaria de ouvir opiniões sobre se a interatividade para humanos tem mais valor, ou se o mais importante é o contexto para agentes
    Link do projeto