Case Study: Making Mermaid Diagrams Work in the Terminal

termaid takes Mermaid source—the text commonly used to describe flowcharts and sequence diagrams—and turns supported diagrams into Unicode drawings that fit in a terminal. It is a Go library and command line program for situations where a browser canvas is unavailable or inconvenient, including command line tools, terminal interfaces, and agent workflows.

The problem is easy to recognize: a diagram that looks fine in a browser can become unreadable in a narrow terminal. Generated Mermaid can also contain HTML tags and inconsistent formatting. termaid cleans that input, parses flowcharts and sequence diagrams, lays them out on a character grid, and draws their nodes and connectors with Unicode box characters. It can adapt a wide left-to-right flow to a top-down layout, and it can return the source when the diagram cannot fit cleanly.

The implementation grew beyond a single renderer. The repository has separate Go packages for sanitization, parsing, layout, canvas drawing, and themes, plus a CLI, an interactive Markdown viewer using Loom, and a separate directory-rendering example that calls the library without the TUI. The test suite currently contains 61 test functions across 12 test files; go test ./... passes across 12 packages. The source and tests total 7,639 Go lines.

One useful episode came from widening the Markdown integration. The parser could already identify a Mermaid diagram by its content, but each Markdown consumer first checked the code fence's language label. That meant an otherwise recognizable diagram inside an unlabeled code fence never reached the parser. Issue 011 described the gap, and commit f5204a5 (2026-09-17) added content sniffing for unlabeled fences while improving fence detection. The lesson is a practical one: a capability deep in a library does not help users if an earlier layer filters out the input before it can run.

The project also records its development as a ticketed sequence. Its first eight issues cover the library foundation, sanitization, flowchart parsing, layout and routing, the drawing canvas, width handling, sequence diagrams, and the CLI. Issues 009 and 010 then drove two examples with different integration costs: an interactive Loom-based viewer and a standalone renderer. At the time of this review, ten of twelve tickets are closed and two remain open. Recent commits include the fence-detection change, REUSE compliance, the standalone example, and releases v0.1.4 through v0.1.6. The log shows 48 commits in the last six weeks, with most landing on September 13 and two follow-up commits on October 1.

The repository's earlier session study describes lean-sprint handoffs and scoped agent work during the initial build. The evidence worth carrying forward is the concrete delivery: a modular renderer, two kinds of diagrams, two distinct examples, a CLI, documentation, and a test suite. A single developer could build these pieces, but delivering them together quickly requires maintaining attention across parsing, graph layout, terminal-width constraints, CLI behavior, examples, packaging, and release hygiene. The ticket history and tests make that breadth inspectable instead of asking readers to take a velocity claim on faith.

There is still a packaging issue to resolve before the repository is ready to serve as a frictionless public Go dependency: go.mod uses a local sibling Loom replacement, while the README and website show GitHub installation paths. That mismatch is tracked in issue 013. The renderer itself has a clear story; the public installation path needs to be just as clear and reproducible.

Facts