How I built a mind map that's just a Markdown list (and why that makes AI streaming almost free)

Amery — Fri, 19 Jun 2026 08:12:38 +0000

Most mind map tools store their data in a proprietary binary blob or lock you into a WYSIWYG editor. When I started Open MindMap, a React component, I made one decision up front that ended up shaping everything else:

The source of truth is a plain, indented Markdown-like list. Nothing else.

That one constraint turned out to cascade into a bunch of properties I wanted but hadn't fully planned for — diff-friendly maps, trivial programmatic generation, and the thing people ask about most: real-time AI streaming. This post walks through how the pieces fit together, from text to tree to SVG.

If you'd rather just play with it: the demo is at mindmap.u14.app and the code is on GitHub (@xiangfa/mindmap, Apache-2.0).

The whole thing in one sentence

text  →  tree  →  layout  →  SVG

Every stage is pure and one-directional, and every stage round-trips back to text. That symmetry is the trick that makes the rest easy.

1. The data model

A mind map is a forest of trees, so the node type is about as boring as you'd expect:

interface MindMapData {
  id: string;
  text: string;
  children?: MindMapData[];
  remark?: string;                 // multi-line note attached to a node
  taskStatus?: "todo" | "doing" | "done";
  // plugin-populated fields:
  tags?: string[];
  anchorId?: string;               // cross-link source
  crossLinks?: CrossLink[];        // cross-link targets
  collapsed?: boolean;
  dottedLine?: boolean;
  multiLineContent?: string[];
}

The important detail is what isn't here: no coordinates, no widths, no colors. Position and style are derived later from the tree, never stored. That keeps the data model serializable and keeps the text the single source of truth.

2. Parsing: indentation is the hierarchy

The parser's only real job is converting leading whitespace into parent/child relationships. The heart of it is a stack keyed by indentation depth:

function parseList(source: string): MindMapData[] {
  const lines = source.split("\n").filter((l) => l.trim().length > 0);
  const roots: MindMapData[] = [];
  const stack: { node: MindMapData; indent: number }[] = [];

  for (const line of lines) {
    const indent = line.length - line.trimStart().length;
    const text = line.trim().replace(/^[-*+]\s*/, ""); // strip bullet marker
    const node: MindMapData = { id: uid(), text, children: [] };

    // climb back up to the correct parent
    while (stack.length && stack[stack.length - 1].indent >= indent) {
      stack.pop();
    }

    if (stack.length === 0) roots.push(node);
    else stack[stack.length - 1].node.children!.push(node);

    stack.push({ node, indent });
  }

  return roots;
}

That's the entire core idea. A line more indented than the previous one is its child; a line at the same or lower indentation pops the stack until it finds its real parent. Multiple top-level lines (or trees separated by a blank line) simply become multiple roots — which is how you get several independent maps on one canvas.

It's O(n) over lines, single pass, no backtracking. Hold that property in mind — it's what makes streaming cheap in section 5.

3. The two layers of syntax

Plain indentation gets you a tree, but a tree of bare strings is boring. The richer syntax lives in two layers that run after the structural parse:

Line-level markers decide what kind of node a line is, before the text is stored:

- React #framework #frontend      → tags: ["framework", "frontend"]
- [x] Ship the parser             → taskStatus: "done"
- [ ] Write the layout engine     → taskStatus: "todo"
  > remember to handle RTL        → remark on the parent node
- Launch {#launch}                → anchorId: "launch"
  -> {#launch} "depends on"       → crossLink with a label

Inline formatting is parsed lazily, only when a node renders, into a small token stream:

// "**bold** and `code`" → [{type:"bold",...}, {type:"text"," and "}, {type:"code",...}]
parseInlineMarkdown(node.text);

Keeping inline parsing lazy matters: you don't pay to tokenize **bold** for a node that's currently scrolled off-screen or collapsed.

Each of these extras is a plugin. There are seven built in (tags, folding, cross-links, LaTeX, dotted lines, multi-line, frontmatter), they're all on by default, and each one is tree-shakeable — a plugin you don't import isn't in your bundle. A plugin is essentially a pair of hooks: one that claims a line during parsing and writes a field onto the node, and one that contributes to rendering. The core parser stays oblivious to all of them.

4. Why the round-trip matters

Because position and style are derived, every transform is reversible:

parseMarkdownList(text)        // text  → MindMapData
toMarkdownList(node)           // MindMapData → text
parseMarkdownMultiRoot(text)   // text  → MindMapData[]
toMarkdownMultiRoot(forest)    // MindMapData[] → text

This is what makes the maps diffable and version-controllable — a one-node change is a one-line diff in git, not an opaque binary delta. It's also why the built-in text editor can flip between a visual map and raw Markdown with no lossy conversion in either direction: they're two views of the same string.

5. Streaming: the part that was almost free

Here's the payoff. An LLM emits a mind map as a Markdown list, token by token. At any instant, the buffer you've received so far is already valid Markdown — a partial list is just a smaller list. So the streaming consumer is almost insultingly simple:

let buffer = "";
for await (const chunk of llmStream) {
  buffer += chunk;
  mindMapRef.current?.setMarkdown(buffer); // re-parse the partial text every tick
}

Each tick re-runs the O(n) parser over the whole buffer and hands React a fresh tree. Two things keep this smooth instead of janky:

The parser is cheap and total. It never throws on incomplete input — a half-written line is just a node with short text that'll get longer next tick. There's no "wait for a complete element" state machine to stall on.
The diff between ticks is tiny. Re-parsing produces a tree that's almost identical to the last one, so React's reconciliation and the SVG re-layout only touch what changed. The map visibly grows rather than flashing and redrawing.

The optional built-in AI input bar wraps this and talks to any OpenAI-compatible endpoint, but the streaming behavior isn't special-cased for it — anything that can call setMarkdown with a growing string gets the same effect. The component never had to know an LLM existed. That's the whole point of making text the interface.

One honest caveat: the AI input bar sends the API key straight from the browser. That's fine for local prototyping, but in production you should put a proxy in front of it so the key stays server-side.

6. Layout: from tree to coordinates

This is where the real work hides, because SVG gives you zero automatic layout — you place every pixel yourself.

The layout pass is a recursive walk that assigns each node an (x, y):

x comes from depth. Each level steps a fixed distance away from the root.
y comes from subtree size. A node is centered against the vertical span of its children, so a parent sits opposite the middle of its branch.

function measureSubtree(node: MindMapData): number {
  if (!node.children?.length || node.collapsed) return NODE_HEIGHT;
  return node.children.reduce((h, c) => h + measureSubtree(c), 0);
}

For the default balanced ("both") layout, the root's top-level branches are split between the left and right sides to keep the two halves roughly even in height, then each side lays out independently — left side mirrored. left and right modes just send every branch one way.

Each top-level branch also gets a stable branch index, which is how coloring works: the index maps to a CSS variable (--mindmap-branch-0 … -9) and lands on the SVG element as data-branch-index, so you can theme an entire branch with one selector.

Text width is the gnarly bit. SVG won't tell you how wide a string renders until it's in the DOM, so node sizing has to either measure rendered text or approximate it — and getting that wrong means edges that don't quite meet their boxes. It's the least glamorous and most fiddly part of the whole component.

7. Rendering: why pure SVG

Everything draws as SVG — no canvas, no external graph/layout library. That's a deliberate tradeoff:

Crisp at any zoom. Vectors don't pixelate, so deep zoom stays sharp.
Themeable with plain CSS. Nodes, edges, and tags are real elements with semantic classes, so you style them with ~30 CSS variables instead of re-rendering a bitmap.
Exportable for free (next section).

Edges are SVG paths — a curve from a parent's anchor point to each child's. Selection, the add-child button, fold toggles, and tags are all just more SVG nodes layered on. The cost you pay for this is that very large trees mean a lot of DOM nodes, so there's a ceiling where canvas would win on raw throughput. For the document-sized maps this is built for, vectors are the right call.

8. Export falls out of the rendering model

Because the live view is SVG, exporting it is mostly serialization:

SVG export walks the rendered tree and inlines a <style> block with the resolved CSS values, plus the same semantic classes and data-branch-index attributes. The result renders correctly as a standalone file with no external stylesheet.
PNG export draws that SVG onto a canvas at high DPI and reads back a blob.
Markdown export is just toMarkdownList again — the round-trip from section 4.

const svg = ref.current.exportToSVG();      // string
const png = await ref.current.exportToPNG(); // Promise<Blob>
const md  = ref.current.exportToOutline();   // markdown list

No separate "export renderer" to keep in sync with the on-screen one, because there's only ever one renderer.

9. What's still hard

In the spirit of being honest rather than selling:

Text measurement is the perennial source of layout bugs, as mentioned. Web fonts loading late can shift sizing after first paint.
Large trees push the DOM-node-count ceiling. Folding helps; virtualization of an SVG tree is a project of its own.
Cross-links break the clean tree model on purpose — they're a second edge layer drawn between arbitrary anchors, and routing them through a dense map without crossings is genuinely unsolved here.
Browser-side API keys for the AI bar need a proxy in real deployments.

None of these are unique to this project; they're the standard taxes you pay for "render a graph in the browser, from text, live."

Takeaways

If there's one transferable idea here, it's this: pick a plain-text representation as your source of truth, and a surprising number of features stop being features and start being consequences. Diffability, version control, programmatic generation, lossless editing, and incremental/streaming rendering all fell out of "it's just a Markdown list" — I didn't build them one by one.

The code is open source (github.com/u14app/mindmap, Apache-2.0) and on npm as @xiangfa/mindmap. I'd genuinely like feedback on the syntax design and the parsing/streaming approach — and if you spot a smarter way to handle the text-measurement problem, please tell me.

DEV Community: Amery