24. Mind maps

24. Mind maps

A mind map is a Markdown list of topics under a # Title. It is a page of its own (type: mindmap) or a ```mindmap fence inside a slide, an article, a guide page or any other document. The browser lays it out, draws the lines, and lets the reader fold branches, move topics, and open linked maps with a zoom. Without JavaScript (a screen reader, a feed, a print of the source) the map is the nested list it was written as.

A mind map page#

---
type: mindmap
title: The Thursday Promise
description: Every hand-off between "Buy now" and the doorstep.
layout: map
lines: curved
nodes: box
map-theme: auto
watermark: Northwind Logistics
watermark-position: corner
---
# The Thursday Promise

- Checkout
  - Cart & address
  - Payment → payments.md
  - Promise date {badge=Thu}
- Warehouse → warehouse.md
  - Picking
  - Label printed → slides: talk.md#7
- Delivery
  - Dusk departure ![The first vans](img/dusk.jpg)
  - [!sticky] Drivers asked for a later cut-off on Thursdays.

si build writes one self-contained HTML file per map file (into --output like every other page) and lists it on the index as N maps; si play and si serve serve it live; si check reports its problems. The page fills the window.

title, description, theme, mode, accent, fonts, lang work as on any page. layout, lines, nodes, map-theme, view, camera, kind, floors and flow in any other file draw a warning: a fence takes them as options instead.

Topics#

One list item is one topic; a nested list holds its children; the order is the order on the map. The central topic is the # Title (without one, the page title).

Options combine: - Checkout {badge=Thu collapsed} → checkout.md. -> works as well as →. A code topic:

- Retry with backoff
  ```go
  for try := 1; try <= 5; try++ {
      time.Sleep(backoff(try))
  }
  ```

Many maps#

One file per map is the usual structure: link them with → other.md. The linked mind map files (and the ones they link, cycles included) are inlined into the page, so drill-down works offline from one HTML file, and a breadcrumb leads back. One big file works too: separate the maps with --- and give each a # Title {#id}:

# Payment

- Refunds → #refunds

---

# Refunds {#refunds}

- Partial
- Full

A map's id is its {#id}, or its title as a slug. On a page, page.html#refunds opens that map first.

In a slide or a document#

## Where an order goes

```mindmap layout=right lines=tapered theme=harbor
# Order
- Checkout
  - Payment
- Delivery {badge=Thu}
```

The fence takes layout=, lines=, nodes=, theme=, view=, camera=, floors=, kind= and flow= (the same values as the front matter; theme= is the map theme): ```mindmap view=3d camera=perspective. Topics, links and drill-down work as on a page; → file.md inlines that map file. In a slide the map is as tall as --si-figure-max; in a document --si-mm-height. The map grows in each time its slide comes on screen. Two fences with the same title on one page keep their own ids.

One branch per click. On a slide, steps (or reveal=branches) makes each first-level branch a build step: → shows them one by one, in 2D and in 3D, and they count as the slide's steps, so put one [CLICK] per branch in Notes::

## Where a promise breaks

```mindmap steps flow=on layout=right
# A late parcel
- Payment
  - Bank timeout
- Warehouse
  - One short-staffed shift
- Road
  - A cut-off that leaves too early
```

Notes: (1 min)
A late parcel almost always has one of three causes. [CLICK] Payment… [CLICK] The warehouse… [CLICK] And the road…

In a document steps is reported (there are no clicks there); every branch shows.

Reading a map#

Moves made in the browser last until the page reloads; write them down as {pos=…} / {branch-pos=…} to keep them. On a narrow portrait screen (a phone) any layout is drawn as right, which stays readable.

In 3D#

---
type: mindmap
title: The Thursday Promise
view: 3d
camera: iso
floors: on
---

view: 3d (or view=3d on a fence) draws the same maps as rounded pills on a floor: the central topic is the tallest, deeper topics lower, each a matte shade of its branch colour with a soft shadow. Lines are cables on the floor with dots flowing along them (tapered draws as curved). Pictures, badges, link chips, sticky notes, code topics and the watermark are printed on top of the pills; colours and fonts come from the same --si-mm-* tokens, so the page theme, dark mode and the map themes all apply.

With floors: on, each map a topic links to (→ payments.md, → #refunds) hovers as a glass floor above that topic, joined by a dashed beam, so a map and the maps it opens read as one building.

Kinds

---
type: mindmap
title: Payment
view: 3d
kind: toy
---

```mindmap view=3d kind=bricks
# One safe retry
- Wait thirty seconds {badge=30_s}
- Same idempotency key
- One try only
```

The kind button in the 3D tools cycles Blocks → Bricks → Toy; the Markdown only sets the start. bricks and blocks take their colours from the --si-mm-* tokens; toy keeps its own candy palette and turns to a night scene on a dark page or a dark map theme. Search, Play (the dimmed branches include studs and outlines), drill-down, the cards and the flow dots work the same in every kind.

The 3D view uses three.js (r128, MIT), inlined into the page like everything else (no network): about 620 KB, only on pages that have a map starting in 3D. Pages with 2D maps only stay small and show no 3D button. A folder or site with several 3D maps can carry three.js once: si build maps/ --share-assets (and --no-inline-media, which already puts files beside the pages) writes it to _si/three.min.js next to the pages and links it, so each 3D page is about 600 KB smaller (the example maps: 2.1 MB → 1.5 MB); those pages then need the _si/ folder beside them. Without the flag every page stays one self-contained file. A browser without WebGL shows the map in 2D with a short note. Reduced motion skips the grow-in, the flow and the camera flights.

On a phone held upright, the 3D view starts closer, on the central topic and its first ring of branches; pan, zoom or Fit for the rest. Its List tool shows the map as the nested list it was written as, and Map brings the 3D view back.

Looks#

Branch colours come from --si-mm-1 … --si-mm-5 (by default the theme's accent, second accent, ok, warn and a mix of accent and crit), so every built-in theme and dark mode work. A map-theme (or theme= on a fence) sets every --si-mm-* token at once; your CSS can set any of them:

.si-mindmap { --si-mm-1: #0f766e; --si-mm-grid: rgb(0 0 0 / .05); }
.si-mindmap { --si-mm-hand: "Caveat", cursive; }  /* load it with fonts: google:Caveat */

The tokens (si --export css-rules lists them all): --si-mm-bg, --si-mm-fg, --si-mm-muted, --si-mm-surface, --si-mm-line, --si-mm-accent, --si-mm-on-accent, --si-mm-1 … --si-mm-5, --si-mm-font, --si-mm-mono, --si-mm-hand, --si-mm-grid, --si-mm-sticky, --si-mm-sticky-fg, --si-mm-height.

Editing in the Studio#

si --web (and the desktop app, which runs it) opens a mind map page in the map editor: the map itself, drawn by the same runtime, with a panel for the selected topic and one for the page. Text / Map in the bar above switches between the Markdown and the map; Map is the default for a mind map page, and a new map from New → Mind map opens there. In any other file, put the cursor in a ```mindmap fence and press Map in the bar that appears.

The topic panel edits the text, the badge, what it opens (#map, a mind map file, slides: deck.md#N, a URL; the list suggests them), a picture from the workspace and its alt text, sticky note, folded, and a code topic's language and code (Add code makes one). The page panel sets every front matter key of the table above (on a fence: its options), switches between the maps of the file, and adds a map (--- and # New map {#new-map}). Every change is written back into the Markdown by si itself, as one undoable change, and saved like any edit; the rest of the file (front matter, comments, other text) is kept as it was. Topics of a linked map that comes from another file show, but are edited in their own file.

Exports#

si build map.md --svg              # every map: map-<id>.svg (standalone, fonts inside)
si build map.md --png --scale 3    # map-<id>.png at 3× (default 2×)
si build map.md --pdf              # pdfs/map.pdf: one page per map, sized to it
si build map.md --mp4              # map.mp4: the first map's Play, branch by branch (needs ffmpeg)

Exports draw the 2D map (a view: 3d map too), with its theme, lines, moved topics and watermark; the PDF also has the linked maps, and a map › topic there jumps to its page. They need headless Chrome, like --pdf for decks. --mp4 films Play: the overview, then each first-level branch with the rest dimmed (2.5 s each, a short zoom between), and the overview again; it also needs ffmpeg (brew install ffmpeg), an optional tool like Chrome. A view: 3d page is filmed in 3D: each Play view is rendered by Chrome's software WebGL in the page's kind, camera and theme, held 2.5 s and dissolving into the next.

Other mind map tools#

si mindmap import plan.opml          # → plan.md (also .mm FreeMind, .xmind XMind, .mmd Mermaid)
si mindmap import plan.xmind -o maps/plan.md
si mindmap export map.md --to xmind  # → map.xmind (opml, freemind, xmind, mermaid)
si mindmap export map.md --to mermaid --map refunds -o -   # one map, to stdout

Import keeps the topics, their order and web links; every XMind sheet becomes a map. Export writes one map (the first, or --map id); XMind takes every map, one sheet each. Pictures, badges, sticky notes and code stay in si. Import never overwrites a file.

In the terminal#

si play talk.md --terminal and si --terminal draw a mind map (a fence on a slide, or a mind map page in the preview) as a tree: ✲ the central topic, ├─ └─ its branches, → target for links, [badge], ▨ a picture, ✎ a sticky note, ‹go› a code topic. In the terminal Studio, focus the preview (Tab) to edit the tree: ↑ ↓ pick a topic, Enter renames, c adds a child, o a sibling, x deletes, [ ] move it; e still opens the file in $EDITOR.

What si check reports#

A missing file (→ other.md, a picture), a map id that does not exist (→ #ghost), an unknown topic option ({size=3}), a pos= without two numbers, an unknown fence option or value, steps outside a slide, a map with no topics, and unknown front matter values. A slide with steps counts one step per branch, so its [CLICK] cues are checked like any build.

Example: examples/mindmap/ (three linked maps: thursday.md in 3D with its linked maps as floors, payments.md with two maps in one file, warehouse.md in 2D, org layout with orthogonal lines), and the article examples/article/retry.md has a fence. si new ideas --type mindmap writes a starter (--type mindmap3d one that starts in 3D).