Markdown Mindmap

Markdown Mindmap

An Obsidian plugin that renders configurable mind maps (leveled, left-to-right trees) live from your notes' frontmatter links. Each map is a single fenced ```mindmap code block, so you can drop as many maps as you like anywhere in your vault. There is no separate data file to keep in sync: the tree is rebuilt from your notes every time you open it.

Point it at some folders, tell it which frontmatter field links each note to its parent, and it draws the graph: a column per level, curved edges, hover to highlight a node's lineage, click to open the note, collapse/expand subtrees, filter, and search.

It ships as two adapters over one shared core (src/graph.ts): the Obsidian plugin (the full experience described below, rendered inline in a note) and a VS Code extension (a command opens the map in a panel — see VS Code). The feature list below describes the Obsidian plugin; the VS Code adapter is intentionally minimal for now (render + pan/zoom + click-to-open).

Screenshots

Features

• Live from frontmatter. Folders become columns; frontmatter links become edges. Add or remove a note and the map updates.
• Per-level card design. Pick which fields show as title / subtitle / meta per level; cards auto-size to their content.
• Edges from links. A [[wikilink]], plain title, basename, list, or nested field (customFields.serves) on either end of an edge.
• Secondary (dashed) links. Mark cross-links that should draw dashed and stay out of the layout spine (e.g. "also relates to").
• Bar charts & progress bars. Render a 0–100 field as a progress bar, or a list field as a stacked count-by-category bar.
• Multi-select filters and saved views. Toggle-chip filters per property (OR within a property, AND across), then save named filter combinations back into the map block. Each saved view also remembers which subtrees are collapsed.
• Export. Save the current map next to the note as a standalone HTML file or an editable Excalidraw drawing.
• Search highlight. A search box that spotlights matching cards and dims the rest.
• Collapse / expand any subtree, focus a node's lineage/subtree, pan / zoom / fit / fullscreen; click a card for a dialog with its linked parents/children, optional properties, and the rendered note.
• Theme-aware. Uses Obsidian CSS variables, so it follows your light/dark theme.

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]]

Install

Community plugins (recommended)

Markdown Mindmap is in the Obsidian community plugin store:

1. Settings → Community plugins → Browse.
2. Search "Markdown Mindmap", Install, then Enable.

Updates arrive through Obsidian's normal plugin-update flow.

Manual (local testing / latest build)

1. Get the three build files (main.js, manifest.json, styles.css) — either from a Release or by building from source (npm install && npm run build).
2. Copy them into <your-vault>/.obsidian/plugins/markdown-mindmap/.
3. Reload Obsidian, then Settings → Community plugins → enable "Markdown Mindmap".

BRAT

Once a release is published, install with BRAT: Add beta plugin → kikocastro/markdown-mindmap. BRAT-managed plugins also survive Obsidian Sync, unlike a hand-copied folder.

Quick start

Put this in any note (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]
```

A runnable copy of this map, with sample notes, lives in examples/mindmap-demo/. Copy that folder into your vault root and open Mindmap demo.md.

Configuration reference

Top level

layout (all optional, defaults shown)

Each level

Each card

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

bars — either a field name (string) or a map:

bars: demand is shorthand for bars: { field: demand, category: parens }.

Each edge

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. A value may be a single link or a list. A note's first non-secondary parent is its layout parent (single-parent tree); any extra parents still draw edges.

Advanced example

A product strategy tree, showing secondary dashed links, demand 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]
```

Interactions

• Search box — spotlight cards matching title / sub / meta, dim the rest.
• Filter chips — multi-select per property (OR within, AND across), with options sorted alphabetically.
• Saved views — save the current filter combination, apply it from the dropdown, edit it, or delete it. Each view also stores which subtrees are collapsed, so applying it restores that shape. Saved views are written to the block's views: key.
• Export — save the current map next to the note as a standalone .html file or an editable .excalidraw drawing.
• Hover a card — highlight its full up/down lineage.
• Click a card — open a dialog: title + file name, level badge, progress/demand breakdown, its linked parents, siblings, and children (click one to jump the dialog there), optional frontmatter properties, the rendered note, "Open note", and "Focus".
• Focus from a card dialog — show that node, its ancestors, and its primary descendants; click empty map space to clear focus.
• Titles only — toggle the toolbar button to hide each card's subtitle, meta, bars, and labels, leaving just the title.
• + / − on a card — collapse / expand its subtree.
• ⟨ / ☰ — collapse the toolbar to a single button (and expand it back) when it gets in the way.
• ? — open the quick-reference help dialog.
• ⛶ — fullscreen. Reset — clear filters/search/collapse/focus and refit.
• Drag to pan, scroll to zoom.

Development

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

Obsidian only loads 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.)

VS Code

The same core also 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.

Run it from source:

1. Open this repo's folder in VS Code (the adapter lives in src/vscode/).
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 that contains a ```mindmap block (e.g. mindmap-demo/Mindmap demo.md).
4. Command Palette (Cmd/Ctrl+Shift+P) → Markdown Mindmap: Open Map. The graph opens in a panel beside the note: drag to pan, scroll to zoom, click a card to open that note.

Notes:

• Config source: the active note's first ```mindmap block (same YAML as Obsidian).
• 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 from the Obsidian version by design.
• Current scope: render + column headers + pan/zoom + click-to-open. The toolbar (search, filter chips, fullscreen, reset), collapse toggles, and the note dialog are Obsidian-only for now.

Limits

• from: is folder-only (no tag / Dataview queries yet).
• Link resolution matches a wikilink, basename, or title — not an arbitrary shared field value (so a keyword like stage: claims won't auto-link unless a note of that basename/title exists).
• Layout centring assumes primary edges connect adjacent levels.

License

MIT © Kiko Castro