HN Reader

Mermaid ASCII: Render Mermaid diagrams in your terminal

418

9 days agoby mellosouls

https://github.com/AlexanderGrooff/mermaid-ascii

https://mermaid-ascii.art/

Really cool. Alexander Grooff (this is based on his go library [0]) did a great job.

[0]: https://github.com/AlexanderGrooff/mermaid-ascii

I think I ran into a bug, the "start" edge is not rendered. This is from https://agents.craft.do/mermaid:

    stateDiagram-v2
      [*] --> Idle
      Idle --> Active : start
      Active --> Idle : cancel
      Active --> Done : complete
      Done --> [*]

    ┌──────────┐
    │          │
    │          │
    │          │
    └─────┬────┘
          │     
          │     
          │     
          │     
          ▼     
    ┌──────────┐
    │          │
    │   Idle   │
    │          │
    └─────┬────┘
          ▲     
          │     
      cancel   
          │     
          ▼     
    ┌─────┴────┐
    │          │
    │  Active  │
    │          │
    └─────┬────┘
          │     
          │     
      complete  
          │     
          ▼     
    ┌──────────┐
    │          │
    │   Done   │
    │          │
    └─────┬────┘
          │     
          │     
          │     
          │     
          ▼     
    ┌──────────┐
    │          │
    │          │
    │          │
    └──────────┘

8 days agoby dmos62

I’m not entirely sure why there’s a push toward ASCII diagrams (perhaps influenced by AI usage). Mermaid and PlantUML are already text-based representations, and what most users actually want is a rendered diagram in a standard, widely recognized notation—primarily for humans, not machines.

ASCII diagrams are inherently constrained by printable characters, which makes them hard to standardize and limits their expressiveness compared to proper diagram renderers.

8 days agoby smilingleo

I love ASCII diagrams! The fact that I can write a diagram that looks equally wonderful in my terminal via cat as it does rendered on my website is incredible.

A good monospaced font and they can look really sharp!

I will definitely give this tool a shot.

I will also shout out monodraw as a really nice little application for building generic ASCII diagrams- https://monodraw.helftone.com/

8 days agoby jonfw

The actual Mermaid ASCII renderer is from another project [0]. This project transliterated it to typescript and added their own theming.

[0]: https://github.com/AlexanderGrooff/mermaid-ascii

8 days agoby tempaccsoz5

While Mermaid gets the limelight, Kroki[1] offers: BlockDiag, BPMN, Bytefield, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag, C4 with PlantUML, D2, DBML, Ditaa, Erd, Excalidraw, GraphViz, Nomnoml, Pikchr, PlantUML, Structurizr, Svgbob, Symbolator, TikZ, Vega, Vega-Lite, WaveDrom, WireViz, and Mermaid.

My Markdown editor, KeenWrite[2], integrates Kroki as a service. This means whenever a new text-based diagram format is offered by Kroki, it is available to KeenWrite, dynamically. The tutorial[3] shows how it works. (Aside, variables within diagrams are also possible, shown at the end.)

Note that Mermaid diagrams cannot be rendered by most libraries[4] due to its inclusion of <foreignObject>, which is browser-dependent.

[1]: https://kroki.io/

[2]: https://keenwrite.com/

[3]: https://www.youtube.com/watch?v=vIp8spwykZY

[4]: https://github.com/orgs/mermaid-js/discussions/7085

8 days agoby thangalin

Also see https://arthursonzogni.com/Diagon for text to ascii.

I have a list of text to diagram tools here https://xosh.org/text-to-diagram/ but not many are text to ascii. There are a few text to ascii sequence diagram tools.

8 days agoby smusamashah

The live demo requires some download of an AI agent platform? I'd really like to try this but not if that's what's required.

8 days agoby a_t48

Wow! It has this:

  Subgraph Direction Override: Using direction LR inside a subgraph while the outer graph flows TD.

With this, you should be able to approximate swim lane diagrams, which is something Mermaid lacks.

The last time I checked, Mermaid couldn't render subgraphs in a different direction than the overall graph.

8 days agoby rahimnathwani

If you like Obsidian.md but can't quite recommend it for less technical folks, these devs' Craft notes spaces are a great alternative:

https://www.craft.do/

While great for individuals, it's particularly strong out-of-the-box for teams, or even teams of teams with two levels of grouping.

They bring the same ... craft (ahem) ... to the whole product as shown in their Craft Agents or this renderer, with a strong foundation originally started in the Markdown philosophy. Check out the founder's story on their About page for a refreshingly LLM-free backgrounder.

8 days agoby Terretta

Pair this with Unicode plots[0] and you're set!

[0]: https://github.com/JuliaPlots/UnicodePlots.jl

8 days agoby dleeftink

> Aesthetics — Might be personal preference, but wished they looked more professional

Im sold. Love mermaid but totally agree.

8 days agoby jackconsidine

Note that by doing ASCII you’re sacrificing possible accessibility; WCAG 1.0 specifically called ASCII images out as a problem in 1999.

(Mermaid isn’t accessible by default either, but there’s current work in that direction: https://github.com/mermaid-js/mermaid/pull/7349)

8 days agoby robin_reala

I've been working on https://github.com/btucker/selkie which is a complete implementation of the Mermaid parser & renderer in rust as an experiment in what's possible with Claude Code. It's still rough around the edges, but I've been blown away by what's been possible. (I'm now using it as a test repo for https://github.com/btucker/midtown)

Playground here: https://btucker.github.io/selkie/

One of the cool features is it can use kitty to output diagrams direct to the terminal (if kitty is supported like in ghostty).

I'm planning to blog about the whole process soon.

8 days agoby btucker

This is a really cool project, and incredible traction - great job! I can see how this would work well with Claude Code to quickly explain what's going on.

I've worked on a similar project, but instead of going the ASCII route, we decided to lean into interactivity for code exploration. The angle is more around empowering human understanding, instead of agent understanding. We also chose D2 (and are looking to support Mermaid soon too).

Would love to hear others' thoughts on whether interactivity for humans is more valuable vs context for agents.

https://github.com/unslop-xyz/noodles

8 days agoby joopie

Looks awesome, perfect for a feature request for CC [0] I opened a while back.

[0]: https://github.com/anthropics/claude-code/issues/14375

8 days agoby reboot7417

The ASCII output is the missing piece for AI-assisted coding workflows. LLMs can spit out Mermaid, but you can't see the diagram inline in a terminal/code-review context. This fixes that.

8 days agoby nulone

I love this project! I am minimalist web-gui averse being embedded dev and all my documentation is plain ascii. This tool will prove useful for posterity. Thanks!

8 days agoby javier_e06

While a bit nifty to have this available in the TS/JS ecosystem for web usage... I'm not sure it'd be my first thing if I were using such a thing as a CLI.

Adjacent... I am somewhat curious if a well crafted rust library/app might work better via WASM since it's a relatively simple input/output scenario... I've done similar for input sanitization tasks in the past and it worked better than JS/TS.

8 days agoby tracker1

Nice! Mermaid diagrams show up as their source code in Github Pages so perhaps this can be resolved now

https://github.com/orgs/community/discussions/65040

8 days agoby hbcondo714

I've had issues with other CLI wrappers there. ASCII output is a nice touch for including diagrams directly in code comments without breaking formatting. Does it handle large graphs well, or does the text wrap get messy? We tried using `graph-easy` for this before but the syntax was annoying. 6.

8 days agoby doanbactam

Am I reading this right and it doesn’t need any DOM or browser engine at all? That would indeed be awesome.

8 days agoby rcarmo

And there's a SKILL for that: https://skills.sh/intellectronica/agent-skills/beautiful-mer...

8 days agoby intellectronica

It seems like the ASCII/Unicode mode doesn't work all that well: https://agents.craft.do/mermaid#sample-6

8 days agoby mjaniczek

Show HN: Mermaid ASCII Diagrams - https://news.ycombinator.com/item?id=41847407 - Oct 2024 (50 comments)

8 days agoby dang

I get a sense of deja vu. There was another such project posted within the last 3 months, and another within last 6 months. I should have bookmarked them, because at least one of them was an open library (I think).

8 days agoby peanutz454

I really tried to like Mermaid but the difficulty in styling gets tiring after a while. Went back to trusty .puml for sequence diagrams - much more expressive when it comes to styling.

8 days agoby noisy_boy

Nice one! I had my own spin on this issue as well, but from the other angle https://github.com/probelabs/maid

Getting AI to generate valid mermaid diagrams on scale extremely hard. With maid i'm hitting 100% accuracy.

Maid is basically built from scratch mermaid parser, without any dependnecies, which knows how to auto-fix common AI slop diagramming issues.

8 days agoby LeonidBugaev

I love Mermaid and Markdown as a combination for documentation.

I wonder if we can get the ASCII render to run inside Vim/NeoVim?

8 days agoby Lio

How is the LaTeX compatibility? Base mermaid's LaTeX compatibility is quite sparse.

8 days agoby wyes

Looks really useful to document complex applications, I will give it a try.

8 days agoby peter_retief

nice project. previously, I used other tools to draw diagrams manually when I needed to add them to source code comments. You solved a big problem. I really appreciate it.

8 days agoby lasgawe

See also:

https://github.com/1jehuang/mermaid-rs-renderer

Just submitted a HN thread about it:

https://news.ycombinator.com/edit?id=46807750

8 days agoby dochtman

This is great, I will definitely make use of this!

8 days agoby lubujackson

In the live demo, I am confused about some of the ascii renderings. (Unless I am missing something, they appear incorrect/inconsistent with the SVG.), https://agents.craft.do/mermaid

So for the "All Edge styles"

    graph TD
      A[Source] -->|solid| B[Target 1]
      A -.->|dotted| C[Target 2]
      A ==>|thick| D[Target 3]

Results in the ascii

    ┌──────────┐                                     
    │          │                                     
    │  Source  ├─thickted─────┐                      
    │          │        │     │                      
    └─────┬────┘        └─────┼────────────────┐     
          │                   │                │     
          │                   │                │     
        solid                 │                │     
          │                   │                │     
          ▼                   ▼                ▼     
    ┌──────────┐        ┌──────────┐     ┌──────────┐
    │          │        │          │     │          │
    │ Target 1 │        │ Target 2 │     │ Target 3 │
    │          │        │          │     │          │
    └──────────┘        └──────────┘     └──────────┘

(The svg for this example is maybe misleading, as it looks like un upside down T) But the ascii here has the overlapping words, and you cannot tell the difference in any of the lines.

The Parallel links, example mermaid

    graph TD
      A[Input] & B[Config] --> C[Processor]
      C --> D[Output] & E[Log]

results in ascii

    ┌───────────┐     ┌────────┐
    │           │     │        │
    │   Input   │     │ Config │
    │           │     │        │
    └─────┬─────┘     └────┬───┘
          │                │    
          │                │    
          │                │    
          │                │    
          ▼                │    
    ┌───────────┐          │    
    │           │          │    
    │ Processor ├◄─────────┤    
    │           │          │    
    └─────┬─────┘          │    
          │                │    
          │                │    
          │                │    
          │                │    
          ▼                ▼    
    ┌───────────┐     ┌────────┐
    │           │     │        │
    │   Output  │     │  Log   │
    │           │     │        │
    └───────────┘     └────────┘

This is just wrong isn't it? Why is there an arrow from config to log?

8 days agoby apwheele

Who’s going to make the rehype plugin?

8 days agoby altano

8 days agoby cjlm

very good job nice. i will give a try !

8 days agoby patrick4urcloud