Mind maps

Mind maps are useful when a note is more tree than prose: planning an outline, decomposing a feature, sketching a launch plan, or keeping a hierarchy visible while writing another note.

The mind map surface is intentionally markdown-first. You can work visually, but the durable source remains a readable type: mindmap markdown file.

Choose the right surface

Use one of these two paths:

Inside a Note Tray leaf - best for active drafting. Press Mod+Shift+M to toggle the active note into mind map mode.
Dedicated Mind Map frame - best for reference. Add or swap a frame to Mind Map when you want a specific map pinned beside another editor.

The dedicated frame owns the durable frame state: file path, layout (mindmap or outline), and folded branches. Placement, node-width mode and values, Outline density, and structure guides are remembered per workspace-relative note path in AppSettings, so every frame showing the same note uses the same view settings. A note without saved settings falls back to the frame's leaf state. Shared app preferences such as Theme remain global, while fold and camera state stay frame/session-local.

Start from a blank note

Open a Note Tray leaf.
Open the command palette (Mod+K).
Run Mind Map Setup.
Enter the root title and apply.
Use Tab or O to add child nodes.

The setup command previews the exact candidate markdown before writing. It preserves supported frontmatter, normalizes line endings, and refuses prose, skipped indentation levels, multiple roots, unsupported codecs, or malformed encoded labels; cancel, validation failure, and write failure leave the original file unchanged. After that, every node edit writes back to the markdown file.

Work with a split frame

A common planning layout is:

Put a dedicated Mind Map frame on the left.
Put a Note Tray or External File Editor frame on the right.
Keep the map in mindmap layout while drafting prose beside it.
Switch the map frame to outline layout when you need compact structural editing.

This keeps the map visible without tying the active note's view mode to the reference map.

Keep the file AI-friendly

The source format is deliberately simple:

---
type: mindmap
---

# Launch plan
- Research
  - Customers
  - Competitors
- Build
  - Prototype
  - Review
- Ship
  - Docs
  - Announcement

That makes it easy to ask an AI tool to add branches, rename nodes, or reorganize a subtree. Keep one node per bullet line and use 2-space indentation.

Labels use the mindmap-label-codec: base64url-v1 marker when a label needs an unambiguous encoded representation. In the board, Mod+Enter starts editing and Alt+Enter (Option+Enter on macOS) adds a sibling above; inside the label editor that same key inserts a newline at the caret or replaces the current selection, while plain Enter commits. Structural keys such as Tab, Shift+Tab, O, A, D, H, J, K, and L operate on the tree while focus is not in a text field. Shift+Enter adds a main node from anywhere.

Choose a layout

The frame toolbar exposes Theme, Mode, and Settings. Mode switches between the map and Outline. In the map, choose one of these placements:

Free keeps branches on their remembered left/right sides and lays them out around the root.
Vertical puts the root above a preorder stair of visible rows.
Horizontal puts the root in the upper-left, top-level branches in columns on the next row, and descendants below their branch.

At a glance, the three placement geometries look like this:

Free                 Vertical                    Horizontal
      [A]             [Root]                     [Root]
       /                 |                    [A]  [B]  [C]
[Root]                   [A]                    |    |    |
       \                  |                   [A1] [B1] [C1]
        [B]              [A1]
                         |
                        [A2]

Node width has three modes, including the root: Free grows each node to its measured label with no width cap; Max width grows to the label but wraps at a configurable maximum (180–800px, default 260px); and Fixed width gives every node the same configured width (180–360px). The width slider and number field appear only for Max width and Fixed width. Compact Outline density uses the smaller row spacing; Comfortable is the default. Structure guides can be shown or hidden independently of placement.

Use board features while planning

Create then type - add a node and immediately name it; empty pending nodes are canceled instead of serialized.
Fold badges - collapse branches you are not working on; the badge shows how much is hidden.
Find - use Mod+F to jump to a node label. Hidden ancestors unfold automatically.
Focus mode - press F to dim everything outside the selected subtree.
Context menu - right-click a node for add, edit, fold, and delete actions.
Drag - move a node to a new parent or sibling position; the markdown tree follows.

On touch-sized windows (320px, 360px, and exactly 640px), map controls keep their visual density while interactive targets remain at least 44×44px and the workspace stays contained without horizontal overflow. The small fold badge is a 44px hit area around its visual disc.

Troubleshooting

If a file opens as plain markdown, check that its frontmatter includes type: mindmap.

If the visual map cannot parse the file, switch to edit mode and check for blank lines inside the bullet tree or indentation that is not a multiple of 2 spaces.

If you want a branch fold to survive restart, use the dedicated Mind Map frame. Fold state in the Note Tray view mode is session-local.

Placement, node width, Outline density, and structure-guide settings follow the note across dedicated frames. Switching a frame to another note loads that note's saved settings, or its frame defaults when it has no saved entry.

Mind Map View manual - complete shortcut table and format reference.
Frame Components Reference - provider id, layouts, and persistence behavior.
@takazudo/mindmap-parser - parser and serializer details.

Empty and missing files

The shared EmptyState presentation explains how to start a mind map and links to its Manual. A missing file retains its path in the recovery message. Existing file-choice and creation flows remain the source of truth; guidance does not create a second editor or file format.