Markdown Mindmap

Draw your notes, live. Markdown Mindmap reads the links you already keep in your notes' frontmatter and renders them — as a leveled mind map, a gantt chart, a kanban board, or a causal-loop diagram. There is no second copy of the data to maintain: every map is rebuilt from your notes each time you open it, so the picture can't drift from the source.

A map is one fenced code block, so you can drop as many as you like anywhere in your vault. There are two kinds:

• ```mindmap — a leveled left-to-right tree, switchable between map, gantt, and kanban views of the same notes.
• ```causalmap — a causal-loop diagram for systems thinking, with feedback loops detected automatically.

Point a block at some folders, name the frontmatter field that links each note to its parent, and it draws the graph.

Screenshots

Card dialog	Hover lineage

Saved views	Search highlight	Titles only

Causal map overview	Causal loop spotlight

What you get

• Four pictures from one set of notes — mind map, gantt, kanban, and causal-loop diagram, all driven by frontmatter you already write.
• Cards you design per level — choose which fields become the title, subtitle, meta line, progress bar, category bar, or coloured pills. Cards size themselves to fit.
• Filters, search, and saved views — multi-select chips per property, a search box that spotlights matches, and named filter combinations saved back into the block.
• Navigation that respects the tree — hover to light up a node's whole lineage, collapse any subtree, focus a branch, or open a card for its linked parents, siblings, and children.
• Export — save the current view as a standalone HTML file or an editable Excalidraw drawing.
• Native-feeling — themed with Obsidian's own CSS variables, so it follows your light/dark theme.
• Two hosts — everything above is the Obsidian plugin; a VS Code extension renders ```mindmap blocks from the same core, in a panel.

Install

Community plugins (recommended)

Markdown Mindmap is in the Obsidian community plugin store: Settings → Community plugins → Browse, search "Markdown Mindmap", Install, then Enable. Updates arrive through Obsidian's normal plugin-update flow.

BRAT

For pre-release builds, use BRAT: Add beta plugin → kikocastro/markdown-mindmap. BRAT-managed plugins also survive Obsidian Sync, unlike a hand-copied folder.

Manual

Get the three build files (main.js, manifest.json, styles.css) from a Release or by building from source (npm install && npm run build), copy them into <your-vault>/.obsidian/plugins/markdown-mindmap/, reload Obsidian, and enable the plugin under Settings → Community plugins.

Quick start

Put this in any note and open it in Reading view or Live Preview:

```mindmap
title: Goals → Projects → Tasks
levels:
  - id: goals
    label: GOALS
    from: planning/goals
    card: { title: title, sub: kpi }
  - id: projects
    label: PROJECTS
    from: planning/projects
    card: { title: title, meta: [status] }
  - id: tasks
    label: TASKS
    from: planning/tasks
    card: { title: title, meta: [status], progress: progress }
edges:
  - { from: goals,    to: projects, via: goal }     # each project note: goal: "[[Goal A]]"
  - { from: projects, to: tasks,    via: project }  # each task note: project: "[[Project 1]]"
filter: [status]
```

Three folders become three columns; the goal: and project: frontmatter fields become the arrows between them; status becomes a row of filter chips.

Two runnable demos ship with the repo — copy either folder into your vault root and open its note:

• examples/mindmap-demo/ — vision → areas → features → tasks, exercising per-level colours, a reverse edge, category bars, and a dashed secondary link.
• examples/ost-demo/ — an Opportunity Solution Tree with interview-quote subtitles and a saved view.

See examples/README.md for what each one demonstrates.

How it works

A map is a list of levels. Each level reads notes from a from: folder and becomes a column, left to right in the order you list them. Edges connect levels: an edge says "notes in the child level point up to a note in the parent level via frontmatter field X".

 LEVEL 0          LEVEL 1              LEVEL 2
 ┌──────────┐     ┌──────────────┐     ┌────────────┐
 │  Goal A  │────▶│  Project 1   │────▶│   Task …    │
 │          │──┐  └──────────────┘     └────────────┘
 └──────────┘  │  ┌──────────────┐     ┌────────────┐
               └─▶│  Project 2   │────▶│   Task …    │
                  └──────────────┘     └────────────┘
        edge: project.goal=[[Goal A]]    edge: task.project=[[Project 1]]

By default the linking field lives on the child notes and points up. Set reverse: true when it lives on the parent and points down (a serves: list, say). Mark an edge secondary: true and it draws dashed and stays out of the layout spine — the way to show "also relates to" without distorting the tree.

How links resolve

A via value is matched, in order, against Obsidian's own link resolution ([[wikilink]]), then the target's basename, then its title frontmatter, then its id frontmatter — so pm-style parentId: p-broker-operator hierarchies link up. A value may be a single link or a list.

A note's first non-secondary parent is its layout parent, keeping the drawing a single-parent tree; any extra parents still draw their edges.

How filters treat the hierarchy

A filter only constrains notes that have the property — a note missing it is never hidden by that chip. What differs is what happens to the notes around a match:

• Strict (default). A note that fails the filter hides itself and its whole primary subtree. Right for "show me only the devops tasks", where a parent that isn't devops shouldn't drag its children along.
• filterKeepsHierarchy: true. A match keeps its context: its subtree rides along (a matching epic still shows its subtasks, whatever their own status) and its ancestors stay visible as scaffolding. Right for a roadmap where the tree shape matters.

Collapse applies last either way, so a contracted subtree stays hidden.

A fuller example

A product strategy tree using per-level colours, secondary dashed links, category bars, and progress bars:

```mindmap
title: North Star → Drivers → Opportunities → Roadmap
height: 860
properties: true
levels:
  - { id: northstar, label: NORTH STAR,   from: strategy/north-star,   color: "#1abc9c", card: { title: title, sub: metric } }
  - { id: drivers,   label: DRIVERS,       from: strategy/drivers,      color: "#9b59b6", card: { title: title, sub: metric } }
  - { id: opps,      label: OPPORTUNITIES, from: strategy/opportunities, color: "#e67e22", card: { title: title, labels: [kind, horizon], bars: demand } }
  - { id: roadmap,   label: ROADMAP,       from: strategy/roadmap,      color: "#e74c3c", where: { parentId: null }, card: { title: title, meta: [status], progress: progress } }
edges:
  - { from: drivers, to: opps,    via: ladders-to }
  - { from: opps,    to: roadmap, via: serves }
  - { from: opps,    to: roadmap, via: alsoServes, secondary: true }   # dashed
filter: [horizon, kind, status]
```

The three views

One ```mindmap block can draw its notes three ways. Add a gantt: or kanban: config and a **View** switcher appears in the toolbar; set view: to choose which one opens by default. Filters, search, and collapse are applied before layout, so they behave identically in all three — and a saved view pins the filters and the view type, letting you keep a "devops · gantt" one click away.

```mindmap
title: 2026 Roadmap
view: gantt
levels:
  - id: tasks
    from: strategy/2026 Roadmap_tasks
    where: { parentId: null }
    card: { title: title, labels: [status], meta: [start, due], progress: progress }
  - id: subtasks
    from: strategy/2026 Roadmap_tasks
    card: { title: title, progress: progress }
edges:
  - { from: tasks, to: subtasks, via: parentId }
gantt: { start: start, end: due }
kanban: { groupBy: status }
filter: [status, tags]
```

Map is the default: a column per level, curved edges, cards centred on their children.

Gantt lays the same tree out against a time axis. Rows run from start to end with a progress fill; a task whose dates are equal — or that has only one of them — becomes a milestone diamond, and a task with neither gets a plain row. Bars take their colour from the note's status, matched case-insensitively, with the spaced and hyphenated spellings of each both recognised:

• green — done, complete, completed, closed, shipped
• blue — in progress, in-progress, doing, active, wip, started, ongoing
• grey — todo, to do, to-do, planned, backlog, open, not started, new, pending

Anything else — or a missing status — falls back to the level's colour. A vertical today marker appears when the current date is in range, and hovering a row shows its title, dates, status, progress, and tags.

By default rows sort by start date within the hierarchy — siblings and roots are ordered by date, but children stay grouped under their parent, never flattened. Nested rows share the map's collapse state, so a saved view's collapsed list applies here too.

Kanban stacks the same cards into columns by any frontmatter field. All the card configuration carries over; notes with no value gather under a trailing (none) column.

Keys for all three live in the configuration reference.

Causal maps

A ```causalmap block renders a causal-loop diagram — the multi-connected graph systems thinkers use to diagnose retrospectives and post-mortems and to find leverage points. (Obsidian only for now.)

Each causal variable is a note carrying its outgoing signed edges in frontmatter, so the topology is stored once, on the source note, with no separate edge file:

---
id: untested-code-live # optional, defaults to the file name
label: Untested code live
type: vice # driver | vice | capability | virtue — colours the border
status: active
affects:
  - to: incident # id, note name, or [[wikilink]]
    sign: "+" # "+" moves the same direction (default), "-" opposite
    loops: [R1] # optional: name the loop(s) this edge belongs to
---

The block itself just points at the folders:

```causalmap
title: Engineering system
folders: [systems/nodes]
loopFolders: [systems/loops]   # optional loop cards (id + label) naming detected loops
where: { status: active }
height: 700
```

What the diagram gives you:

• Loops found for you. A bounded simple-cycle search detects every feedback loop and classifies it by sign parity — an even number of - edges makes a reinforcing loop, odd makes a balancing one. There is no hand-maintained loop list to fall out of date.
• A loop rail. Each detected loop becomes a chip (● amber = reinforcing, ● teal = balancing); click it to spotlight exactly that cycle's nodes and edges — the retro-projector view — and click again to release. Hovering shows the whole cycle as an A → B → C → A tooltip. Loops whose edges share a loops: tag take that name and lead the rail alphabetically, with a matching card in loopFolders supplying the display label; untagged cycles get auto names (L1, L2, …) in discovery order.
• A type legend listing the node types actually present, with their colours.
• Signed edges as curved arrows with a +/− badge; negative links draw dashed.
• A deterministic layout. The force-directed placement has no randomness, so the same notes always produce the same picture.

Hovering a node lights up everything it affects and is affected by; clicking one opens the note dialog, with each linked row carrying its edge sign. Search, fullscreen, HTML export, and pan/zoom work as they do in mindmaps.

A runnable copy, with sample cards and loop notes, lives in examples/causalmap-demo/. Copy that folder into your vault root and open Causal map demo.md.

Using a map

The toolbar is a rail down the left: title and search at the top, then chip groups (View, Scale, Density, Rows, one per filter property, and Saved views), then a footer holding Display, Export, and the Reset / Refresh / Help row.

• Search — spotlight cards matching title / sub / meta and dim the rest.
• View chips — flip between map / gantt / kanban (shown once gantt: or kanban: is configured).
• Scale, Density, Rows chips — gantt only: the axis unit (week / month / quarter / year), compact vs comfortable row size for presenting, and show subtasks to expand or contract every parent row at once.
• Filter chips — multi-select per property, OR within a property and AND across them, options sorted alphabetically.
• Saved views — save the current filters and view type under a name, then apply, edit, or delete it from the dropdown. Each view also remembers which subtrees were collapsed. Views are written back into the block's views: key and the selected one into activeView:, so your choice survives a restart.
• Export — write the current view next to the note as a standalone .html file or an editable .excalidraw drawing. Both capture what's on screen: active filters, collapse state, and view type.
• Hover a card — highlight its full up/down lineage, in gantt and kanban as well as the map.
• Click a card — open a dialog with the title and file name, level badge, progress/category breakdown, its linked parents, siblings, and children (click one to jump there), optional frontmatter properties, the rendered note, and Open note / Focus buttons.
• Focus — narrow the map to a node, its ancestors, and its primary descendants. It persists while you pan and click; a Focus: … chip at the top of the rail clears it with ✕.
• Titles only — strip cards back to their titles, hiding subtitle, meta, bars, and labels. (Not shown in the gantt, which draws rows rather than cards.)
• + / − on a card, or a gantt row's toggle — collapse or expand that subtree.
• « / ☰ — collapse the whole rail to a single button when it's in the way, and bring it back.
• Refresh — re-read every note's frontmatter and redraw. A map reads the vault once, when the block renders, so edits to the notes it maps (a changed gantt.end, a new status:) don't show until the block re-runs. Your filters, view type, and collapse state carry over; pan/zoom and search do not, and it exits fullscreen.
• Help opens a quick reference · Fullscreen toggles fullscreen · Reset clears filters, search, collapse, focus, and titles-only, returns to the block's default view, and refits.
• Drag to pan, scroll to zoom. Clicking empty space clears the sticky hover highlight.

Configuration reference

mindmap — top level

levels[]

levels[].card

All card field values are frontmatter property names. Dotted paths work everywhere (customFields.serves, nested.key).

bars takes either a field name or a map. bars: demand is shorthand for bars: { field: demand, category: parens }.

edges[]

gantt

kanban

layout

causalmap

Using Project Manager task notes

Task notes written by the Project Manager plugin (pm-task: true frontmatter with status, start, due, progress, priority, assignees, tags, parentId/subtaskIds, customFields.*) render as-is: point a level's from: at your *_tasks folder, add the gantt: and kanban: blocks, and you're done.

Markdown Mindmap never writes task files — edit the note and the view re-renders. Editing, drag-rescheduling, notifications, recurring tasks, and the table view are deliberate non-goals.

VS Code

The same core drives a VS Code extension (src/vscode/). Unlike Obsidian it does not render inline in the editor — you run a command and the map opens in a panel.

To run it from source:

1. Open this repo's folder in VS Code.
2. Press F5 (Run and Debug → Run Extension). It builds, then opens an Extension Development Host window already pointed at examples/.
3. In that window, open a markdown note containing a ```mindmap block (e.g. mindmap-demo/Mindmap demo.md).
4. Command Palette (Cmd/Ctrl+Shift+P) → Markdown Mindmap: Open Map. The graph opens beside the note: drag to pan, scroll to zoom, click a card to open that note.

Some differences from the Obsidian plugin:

• Config comes from the active note's first ```mindmap block (same YAML).
• from: paths are relative to the workspace root, and links resolve by note basename or title frontmatter — there's no vault link index outside Obsidian.
• Visuals follow your VS Code theme (via --vscode-* variables), so the map looks different by design.
• Scope is render + pan/zoom + click-to-open, for whichever view the block's view: key selects. The toolbar, collapse toggles, and the note dialog are Obsidian-only for now.

Limits

• from: is folder-only — no tag or Dataview queries yet.
• Link resolution matches a wikilink, basename, title, or id, not an arbitrary shared field value: a keyword like stage: claims won't auto-link unless a note of that basename/title/id exists.
• Layout centring assumes primary edges connect adjacent levels.
• Gantt has no dependency arrows and no date-range filtering (filters are discrete values). Dates are read, never written — there's no drag-to-reschedule.
• Excalidraw export is lossy by design: rounded boxes, centred labels, straight arrows — no curves, progress bars, label pills, or column headers.
• Causal-map cycle detection is bounded (at most 64 loops, up to 12 nodes long), so a very dense graph reports the first loops found rather than all of them.

Development

npm install
npm run dev     # esbuild watch → main.js (Obsidian) + dist/ (VS Code)
npm run build   # type-check + production build
npm test        # vitest + coverage

Obsidian loads only main.js, manifest.json, and styles.css. For live iteration, symlink this folder into your vault:

ln -s "$(pwd)" "<your-vault>/.obsidian/plugins/markdown-mindmap"

(If you use Obsidian Sync, prefer a Release + BRAT, or commit the built files — Sync can remove a hand-linked plugin folder it doesn't recognize.)

The pure logic lives in src/core/ behind the src/graph.ts barrel, host-free and fully unit-tested; the Obsidian and VS Code adapters wrap it. See AGENTS.md for the architecture and conventions.

License

MIT © Kiko Castro