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).
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.
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.
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.
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.
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.
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 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.
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)
:
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.
Everything draws as SVG — no canvas, no external graph/layout library. That's a deliberate tradeoff:
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.
Because the live view is SVG, exporting it is mostly serialization:
<style>
block with the data-branch-index
attributes. The result renders correctly as a standalone file with no external stylesheet.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.
In the spirit of being honest rather than selling:
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."
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.