5 ms·

Mermaid ASCII: Render Mermaid diagrams in your terminal

• jonfw 9mo ago
  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/ https://monodraw.helftone.com/
  • mixmastamyk 9mo ago
    ^Unicode.
  • hahahahhaah 9mo ago
    Importantly they also render in your source code. I love a good diagram at the top of a file.
    • deleted 9mo ago
      [deleted]
• deleted 9mo ago
  [deleted]
• jackconsidine 9mo ago
  > Aesthetics — Might be personal preference, but wished they looked more professional Im sold. Love mermaid but totally agree.
• a_t48 9mo ago
  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.
  • csmantle 9mo ago
    The devs should really setup a client-only GitHub Pages for an accessible demo. Judging from skimming the project itself, it's definitely doable without locking into their platform.
• dleeftink 9mo ago
  Pair this with Unicode plots[0] and you're set! [0]: https://github.com/JuliaPlots/UnicodePlots.jl https://github.com/JuliaPlots/UnicodePlots.jl
• wyes 9mo ago
  How is the LaTeX compatibility? Base mermaid's LaTeX compatibility is quite sparse.
• cjlm 9mo ago
  See also graph-easy.online (https://github.com/cjlm/graph-easy-online https://github.com/cjlm/graph-easy-online)
• rahimnathwani 9mo ago
  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.
• tempaccsoz5 9mo ago
  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 https://github.com/AlexanderGrooff/mermaid-ascii
  • AlexanderGrooff 9mo ago
    Thanks for the credits!
    • adiian 9mo ago
      Added it to https://udiagram.com https://udiagram.com
  • forgotpwd16 9mo ago
    Meanwhile they could've just bundled mermaid-ascii and run it on wasm. But then again probably took Claude less than an hour to port this to TS. The main algorithms are 1:1 conversion. https://github.com/AlexanderGrooff/mermaid-ascii/blob/master/cmd/draw.go#L170-L238 https://github.com/AlexanderGrooff/mermaid-ascii/blob/master... https://github.com/lukilabs/beautiful-mermaid/blob/main/src/ascii/draw.ts#L30-L80 https://github.com/lukilabs/beautiful-mermaid/blob/main/src/...
  • pancsta 9mo ago
    And its in Go, so no package management joke involved. I will integrate it into my debugger, thx for the link!
  • dang 9mo ago
    Yikes, good catch. I've changed the link above to the original project now. (Edit: actually, let's use the project home page and put the Github repo in the toptext.) (Submitted link was https://github.com/lukilabs/beautiful-mermaid https://github.com/lukilabs/beautiful-mermaid. mellosouls is a good HN contributor so I'm sure this was well-intentioned.)
    • AlexanderGrooff 9mo ago
• doanbactam 9mo ago
  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.
• lubujackson 9mo ago
  This is great, I will definitely make use of this!
• peanutz454 9mo ago
  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).
• Terretta 9mo ago
  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/ 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.
• nulone 9mo ago
  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.
  • deleted 9mo ago
    [deleted]
  • dizhn 9mo ago
    When I needed to see mermaid diagrams rendered the other day I realized my existing Forgejo instance already supported it so that's what I've been doing. Push to repo and check it out there. Not inline but not a bad place for code reviews. (I am sure all the other forges also support it)
• smusamashah 9mo ago
  Also see https://arthursonzogni.com/Diagon https://arthursonzogni.com/Diagon for text to ascii. I have a list of text to diagram tools here https://xosh.org/text-to-diagram/ https://xosh.org/text-to-diagram/ but not many are text to ascii. There are a few text to ascii sequence diagram tools.
  • brumar 9mo ago
    Great list, thank you!
• thangalin 9mo ago
  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/ https://kroki.io/ [2]: https://keenwrite.com/ https://keenwrite.com/ [3]: https://www.youtube.com/watch?v=vIp8spwykZY https://www.youtube.com/watch?v=vIp8spwykZY [4]: https://github.com/orgs/mermaid-js/discussions/7085 https://github.com/orgs/mermaid-js/discussions/7085
  • afro88 9mo ago
    Edit: See child comments, I misunderstood. Original post below anyway. -- 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
    • jbstack 9mo ago
      Maybe I've misunderstood, but isn't the whole point that it outputs to those other formats? So if you like the way Mermaid outputs look, you'd just output to that?
      • afro88 9mo ago
        Oh, you're right. I misunderstood. I think it was the comparison to mermaid that threw me, and then I checked out the examples
  • 9mo ago
• apwheele 9mo ago
  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 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?
  • wrboyce 9mo ago
    The latter one is a rendering issue I think, the right hand side of Processor is being used as an input from Config and an output to Log but the arrows overlap and become ambiguous.
• LeonidBugaev 9mo ago
  Nice one! I had my own spin on this issue as well, but from the other angle https://github.com/probelabs/maid 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.
  • ijustlurk 9mo ago
    Nice one. Mermaid validation is a huge issue given how mermaid.js is architected. 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.
• maximgeorge 9mo ago
  [dead]
• reboot7417 9mo ago
  Looks awesome, perfect for a feature request for CC [0] I opened a while back. [0]: https://github.com/anthropics/claude-code/issues/14375 https://github.com/anthropics/claude-code/issues/14375
• smilingleo 9mo ago
  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.
  • gregoriol 9mo ago
    You can put ASCII diagrams in code comments. Also Claude code in the terminal can show them.
    • deleted 9mo ago
      [deleted]
  • tuetuopay 9mo ago
    They don't need a renderer, so they can be embedded in source code comments, or in markdown document without requiring e.g. Gitlab to properly render the document. And even then, they're still "rendered" when editing said markdown document.
  • benrutter 9mo ago
    I think context matters, often I might be writing docs in a text format that doesn't support mermaid (some readmes for instance, or a print put in a CLI tool) and want diagrams. 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.
  • dmos62 9mo ago
    A lot of people primarily use markdown and command-line, and, importantly, so do many coding agents (which seems to be the authors' primary use case).
    • esafak 9mo ago
• peter_retief 9mo ago
  Looks really useful to document complex applications, I will give it a try.
• rcarmo 9mo ago
  Am I reading this right and it doesn’t need any DOM or browser engine at all? That would indeed be awesome.
• altano 9mo ago
  Who’s going to make the rehype plugin?
• dochtman 9mo ago
  See also: https://github.com/1jehuang/mermaid-rs-renderer https://github.com/1jehuang/mermaid-rs-renderer Just submitted a HN thread about it: https://news.ycombinator.com/edit?id=46807750 https://news.ycombinator.com/edit?id=46807750
• robin_reala 9mo ago
  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 https://github.com/mermaid-js/mermaid/pull/7349)
  • ozim 9mo ago
    Just imagined what a garbage would screen reader spit out.
• patrick4urcloud 9mo ago
  very good job nice. i will give a try !
• dmos62 9mo ago
  Really cool. Alexander Grooff (this is based on his go library [0]) did a great job. [0]: https://github.com/AlexanderGrooff/mermaid-ascii 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 https://agents.craft.do/mermaid: stateDiagram-v2 [*] --> Idle Idle --> Active : start Active --> Idle : cancel Active --> Done : complete Done --> [*] ┌──────────┐ │ │ │ │ │ │ └─────┬────┘ │ │ │ │ ▼ ┌──────────┐ │ │ │ Idle │ │ │ └─────┬────┘ ▲ │ cancel │ ▼ ┌─────┴────┐ │ │ │ Active │ │ │ └─────┬────┘ │ │ complete │ ▼ ┌──────────┐ │ │ │ Done │ │ │ └─────┬────┘ │ │ │ │ ▼ ┌──────────┐ │ │ │ │ │ │ └──────────┘
• mjaniczek 9mo ago
  It seems like the ASCII/Unicode mode doesn't work all that well: https://agents.craft.do/mermaid#sample-6 https://agents.craft.do/mermaid#sample-6
• Lio 9mo ago
  I love Mermaid and Markdown as a combination for documentation. I wonder if we can get the ASCII render to run inside Vim/NeoVim?
• intellectronica 9mo ago
  And there's a SKILL for that: https://skills.sh/intellectronica/agent-skills/beautiful-mermaid https://skills.sh/intellectronica/agent-skills/beautiful-mer...
• tracker1 9mo ago
  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.
  • tnkuehne 9mo ago
    Quite nice for cloudflare workers as they don’t have access to DOM
• btucker 9mo ago
  I've been working on https://github.com/btucker/selkie 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 https://github.com/btucker/midtown) Playground here: https://btucker.github.io/selkie/ 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.
• joopie 9mo ago
  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 https://github.com/unslop-xyz/noodles
• hbcondo714 9mo ago
  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 https://github.com/orgs/community/discussions/65040
• lasgawe 9mo ago
  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.
• noisy_boy 9mo ago
  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.
• dang 9mo ago
  Related: Show HN: Mermaid ASCII Diagrams - https://news.ycombinator.com/item?id=41847407 https://news.ycombinator.com/item?id=41847407 - Oct 2024 (50 comments)
• javier_e06 9mo ago
  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!
• vamgan 9mo ago
  [dead]
• vamgan 9mo ago
  [dead]
• deleted 9mo ago
  [deleted]