[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 │
│ │
└─────┬────┘
│
│
│
│
▼
┌──────────┐
│ │
│ │
│ │
└──────────┘ASCII diagrams are inherently constrained by printable characters, which makes them hard to standardize and limits their expressiveness compared to proper diagram renderers.
In those contexts, rendered mermaid as html isn't an option, so this really does seem like one of the best calls for human readability.
Also Claude code in the terminal can show them.
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/
https://github.com/AlexanderGrooff/mermaid-ascii/blob/master...
https://github.com/lukilabs/beautiful-mermaid/blob/main/src/...
(Submitted link was https://github.com/lukilabs/beautiful-mermaid. mellosouls is a good HN contributor so I'm sure this was well-intentioned.)
Nothing but good vibes to these guys. Let’s all strive to keep making cool things, and leave things a little better than how you found it ;)
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/
With MermaidJS, converting a diagram inside a web page requires adding a handful of lines to a HTML page. The execution is fast and local.
Kroki is a web-service. To use it in a web page means adding a dependency to an external provider (a free service exists, but asks for fundings). An alternative is self-hosting by running a Kroki container.
A few years ago, I added Mermaid diagrams to a project in a few minutes of work. Had we needed a much more complex tool, maybe I would have gone with Kroki, but not by myself; it would have required a change in the deploying process of the project.
Exactly, which is why KeenWrite has a "Diagram server" setting:
https://i.ibb.co/LXxm33cb/diagram-server.png
> they're just for different use-cases
Sure. A software system could support one plain text diagram format, or support a multitude without tons more effort, architecturally speaking.
There's an example of a fairly complicated graph of chess grandmaster PGM taken from a matplotlib example from the NetworkX documentation website, among some more trivial output examples in the README at https://github.com/scottvr/phart/blob/main/README.md#example...
(You will need to expand the examples by tapping/clicking on the rightward-facing triangle under "Examples", so that it rotates to downward facing and the hidden content section is displayed)
--
To me, the diagrams have an uglier default design. A crazy amount of dropdown shadow (in the examples), stretched fonts (front page example). It doesn't matter how many diagram types you support if the generated diagrams aren't good quality.
Mermaids defaults are good enough. They're not amazing, but I'm also not embarrassed to show them to other engineers, stakeholders etc
Edit: KeenWrite looks excellent btw
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.
Subgraph Direction Override: Using direction LR inside a subgraph while the outer graph flows TD.
The last time I checked, Mermaid couldn't render subgraphs in a different direction than the overall graph.
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.
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.
(Mermaid isn’t accessible by default either, but there’s current work in that direction: https://github.com/mermaid-js/mermaid/pull/7349)
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.
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.
Im sold. Love mermaid but totally agree.
Show HN: Mermaid ASCII Diagrams - https://news.ycombinator.com/item?id=41847407 - Oct 2024 (50 comments)
I wonder if we can get the ASCII render to run inside Vim/NeoVim?
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.
I built a mermaid generation harness last year and even the best model at it (Claude Sonnet 3.7 at the time; 4o was okay, Gemini struggled) only produced valid mermaid ~95% of the time. That failure rate adds up quickly. Had to detect errors client-side and trigger retries to keep server load reasonable.
Having a lightweight parser with auto-fix like this back then would have simplified the flow quite a bit.
https://github.com/1jehuang/mermaid-rs-renderer
Just submitted a HN thread about it:
So for the "All Edge styles"
graph TD
A[Source] -->|solid| B[Target 1]
A -.->|dotted| C[Target 2]
A ==>|thick| D[Target 3]
┌──────────┐
│ │
│ Source ├─thickted─────┐
│ │ │ │
└─────┬────┘ └─────┼────────────────┐
│ │ │
│ │ │
solid │ │
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ │ │ │ │ │
│ Target 1 │ │ Target 2 │ │ Target 3 │
│ │ │ │ │ │
└──────────┘ └──────────┘ └──────────┘
The Parallel links, example mermaid
graph TD
A[Input] & B[Config] --> C[Processor]
C --> D[Output] & E[Log]
┌───────────┐ ┌────────┐
│ │ │ │
│ Input │ │ Config │
│ │ │ │
└─────┬─────┘ └────┬───┘
│ │
│ │
│ │
│ │
▼ │
┌───────────┐ │
│ │ │
│ Processor ├◄─────────┤
│ │ │
└─────┬─────┘ │
│ │
│ │
│ │
│ │
▼ ▼
┌───────────┐ ┌────────┐
│ │ │ │
│ Output │ │ Log │
│ │ │ │
└───────────┘ └────────┘