Mind map

About mind maps

A mind map is a radial diagram that organizes ideas around a central topic, branching outward into subtopics and details. Tony Buzan popularized the format in the 1970s as a note-taking and brainstorming tool; the method has since been adopted widely in education, project planning, meeting facilitation, and knowledge management. The key insight is that non-linear branching mirrors how associative thinking works — faster than outlining, more structured than free-writing.

Schematex mind maps use a Markdown-heading + bullet-list DSL inspired by markmap — a format most people already know. Two layout styles are available: the classic radial map (branches in all directions) and a logic-right horizontal tree. This page documents what the parser accepts today.

1. Your first mind map

The smallest useful mind map: a central topic with two branches, one with a sub-item.

Four rules cover 80% of usage:

1. Start with an optional mindmap keyword on its own line, then a blank line.
2. The root is the single # heading — exactly one is allowed.
3. Use ##, ###, and deeper headings to set branch depth. Heading level equals tree depth.
4. Use -, *, or + bullets to add sub-items under any heading. Each 2-space indent adds one more depth level.

Comments are not supported. Use %% directives (before the # root) for configuration only.

2. Headings and depth

Heading level maps directly to tree depth. # is always the root (depth 0). ## is depth 1. ### is depth 2, and so on up to ###### (depth 5).

mindmap

# Root
## Branch A         ← depth 1
### Sub-branch      ← depth 2
#### Leaf           ← depth 3
## Branch B

Headings can jump levels — #### after ## is valid and produces a node at depth 3. The tree depth is relative to the root, not to the previous heading.

3. Bullets

Bullets extend a heading branch with further detail. Any of -, *, or + is accepted as the bullet marker. Each 2 spaces of indentation adds one level of depth relative to the enclosing heading.

## Risks
- Technical complexity         ← depth 2 (one level under ## Risks)
  - Legacy integrations        ← depth 3 (2 spaces indent)
    - Auth service             ← depth 4 (4 spaces indent)
- Team availability            ← depth 2 again

4. Inline formatting

Node labels support a subset of Markdown inline formatting. The parser tokenizes labels at parse time; the renderer uses the tokens to emit styled text.

The checkbox must be at the very start of the label (before any other text). Inline formatting can be nested: **[bold link](url)**.

5. Layout styles

The %% style: directive selects the layout algorithm. Place it before the # root heading.

%% style: map
%% style: logic-right

map (default) — radial layout, branches spread in all directions from the center. Best for brainstorming and concept maps.

logic-right — horizontal tree, all branches extend to the right. Best for structured outlines and sequential hierarchies.

6. Directives

Directives are %% lines placed before the # root heading. They configure the diagram globally.

mindmap
%% style: logic-right
%% maxLabelWidth: 320

# Wide label root

7. Labels & comments

• Root title: the text after # on the root heading line.
• Branch labels: the text after ##, ###, etc.
• Bullet labels: the text after the - / * / + marker.
• Inline formatting: **bold**, *italic*, `code`, [text](url), [ ] / [x].
• Comments: not supported in the body. Use %% directives before the # root for configuration; %% lines in the body are treated as directives (silently ignored if unrecognized).

8. Reserved words & escaping

Reserved at document start: mindmap (optional keyword) and %% (directive prefix).

Reserved as root: exactly one # heading; a second # heading throws a parse error.

Bullet markers: -, *, + followed by a space. A * that is not followed by a space is treated as an italic marker if it appears inside label text.

Inline conflicts: a label beginning with [ ] or [x] is parsed as a checkbox, not a Markdown link. If you need a label that literally starts with [, write \[ — the backslash escapes the bracket.

9. Common mistakes

10. Grammar (EBNF)

document       = ("mindmap" NEWLINE)? (blank | directive)* node*

directive      = "%%" WS key ":" WS value NEWLINE
key            = "style" | "theme" | "maxlabelwidth"

node           = heading | bullet
heading        = INDENT? "#"+ SPACE label NEWLINE
bullet         = SPACE* bullet-marker SPACE label NEWLINE
bullet-marker  = "-" | "*" | "+"

label          = inline-token*
inline-token   = checkbox
               | "**" inline-token* "**"
               | "*" inline-token* "*"
               | "`" code-text "`"
               | "[" inline-token* "]" "(" url ")"
               | plain-text

checkbox       = "[ ]" SPACE | "[x]" SPACE | "[X]" SPACE

INDENT         = WS*    %% headings may have leading whitespace (ignored)
SPACE          = " " | "\t"

Depth rules:

• Heading # → depth 0 (root)
• Heading ## → depth 1, ### → depth 2, etc.
• Bullet at n leading spaces → depth = lastHeadingDepth + 1 + floor(n / 2)

Authoritative source: src/diagrams/mindmap/parser.ts. If this diverges from the parser, the parser wins — please open an issue.

11. Roadmap

Planned — not yet parseable. Do not use these in generated DSL today; the parser will reject or ignore them.

• %%{init: {…}}%% block — Mermaid-style init block for theme/config; currently only %% line directives are supported.
• Auto-numbered branches — %% numbering: true to prefix each branch with 1., 1.1., etc.
• Callout / note nodes — a special marker to attach a floating annotation box to any node.
• Image nodes — ![alt](url) as an entire node label rendered as an inline image.
• Collapsed branches — %% collapsed: branchId to render a subtree as a single folded indicator.

Track in the GitHub issues if you need any of these sooner.