Arbor

Arbor

Think in branches. Keep one note.

Arbor is a writing-first branching editor for Obsidian. Build a note as small Markdown blocks in a horizontal Branch Editor or a horizontal/vertical Tree Overview, while keeping the note itself as a normal .md file.

No separate canvas file. No sidecar database.

The core idea:

• write in short blocks instead of one long wall of text
• see the current branch, nearby alternatives, and next steps at the same time
• reorganize ideas without copy-paste chaos
• stay inside one note instead of splitting thoughts across many files

Arbor works on desktop, phones, and tablets. It requires Obsidian >= 1.7.2.

Why Arbor

Arbor is for notes where order matters, but thought does not arrive linearly.

Good fit:

• article and essay drafting
• study notes with branches and alternatives
• argument building
• structured brainstorming
• rewriting and rearranging long notes without losing the original Markdown

Arbor is not a canvas, mind map, or whiteboard. It is still note editing, just with a branching spatial view.

Core Features

• Horizontal branching editor for one Markdown note, with left-to-right or right-to-left layout
• Stable block tree with inline editing
• Normal readable Markdown body as the source document
• Visible block markers plus a readable in-note structure footer, with optional evidence for locating card text
• Selected block panel with focused preview and inline editing
• Context-aware dimming so the active branch stays readable
• Drag-and-drop reorder and reparent
• Keyboard-first navigation and structure editing
• Block search with selectable results, highlighted snippets and paths; use arrows and Enter or click to reveal a card
• Zoom, breadcrumbs, view menu, and context menus
• Whole-tree Overview with connected Markdown cards and horizontal, upward, or downward layouts saved per note
• Tree Overview export as a PNG or one-page PDF
• Touch-first phone editor with a focused sibling column and 44 px action controls
• One-finger Tree Overview pan and two-finger pinch zoom
• Automatic and custom palettes through Theme Studio
• Individual card colors and inherited branch colors
• Rendered cards and tree exports follow Obsidian's text font
• Mouse-wheel navigation through sibling blocks and visible branch columns
• Auto-open managed Arbor notes in Arbor view
• File Explorer labels that mark managed notes with ARBOR
• Clean Markdown export copies with an optional YAML frontmatter
• Named Output Profiles for producing several clean versions from one complete tree
• Reconcile unambiguous edits made in normal Markdown mode

Use a clean export copy as the Markdown handoff for Pandoc or another DOCX converter; Arbor does not generate DOCX directly.

Output Profiles

Output Profiles let one Arbor note hold the complete tree while producing different versions such as Draft, Short version, or Final.

• Full tree is built in, always includes every block, and is the default for existing notes.
• Use the profile pill in the Arbor toolbar, then Manage output profiles…, to create, duplicate, rename, delete, or switch profiles.
• In a custom profile, right-click a card to Include block only, Exclude block only, Include subtree, or Exclude subtree. Inherited exclusions stay visible in the editor and explain which parent rule caused them.
• Presets in Output profiles provide Include all, Exclude all, Invert selection, Include only selected branch, Root blocks only, and Reset profile.
• Output preview renders only the included Markdown in the current Arbor view. It never creates a temporary file or changes the source note.
• Export clean copy… exports the active profile and can either omit excluded blocks or keep them as HTML comments. YAML frontmatter can be kept or removed independently.

The source .md always retains the complete Arbor tree. Switching profiles, previewing, and exporting change the output version—not the source content.

Install

Community Plugins (recommended)

Arbor is available in the Obsidian community catalog.

1. Open Settings -> Community plugins -> Browse.
2. Search for Arbor.
3. Install it.
4. Enable it.

Manual install

Use this alternative if you prefer to install the plugin files yourself.

1. Download manifest.json, main.js, and styles.css from the latest GitHub release, not the source-code archives.
2. Create this folder in your vault:

.obsidian/plugins/arbor

3. Place those three files inside it.
4. Open or restart Obsidian so it loads the installed files.
5. Go to Settings -> Community plugins.
6. Enable Arbor.

For updates, use Check for updates in Community Plugins. For a manual update, replace only those three files and restart Obsidian; keep data.json to preserve your settings. See the latest release for changes and any update-specific instructions.

Quick Start

1. Open any Markdown note.
2. Run Open view for current note.
3. Create a root block.
4. Press Enter on a selected card to edit it on desktop, or double-tap it on mobile.
5. Use Ctrl/Cmd + Arrow to grow the structure.
6. Use the right-click menu or the mobile block-actions menu to duplicate, delete, or continue a branch.
7. Turn on Selected block panel from the Arbor menu if you want a focused preview/editor panel.

Rendered links in Branch Editor and Tree Overview are clickable: internal links open their note, heading, block, or PDF destination. Ctrl/Cmd-click or middle-click opens a new tab. A link click stays separate from card selection and editing; double-click the card's ordinary text to edit it.

When Heading Linker is enabled, Arbor can also turn indexed terms and aliases into links to headings in other cards of the same note. Include that note in Heading Linker's glossary sources and highlighting scope, and enable Reading highlighting. Arbor preserves your Markdown, skips headings, code, math and existing links, and leaves ambiguous local targets unlinked. An ordinary click reveals the target card in the current view; Ctrl/Cmd-click and middle-click retain Obsidian's normal new-pane behavior.

Bring content into a card

In Branch Editor (left-to-right or right-to-left) and Tree Overview, drop supported text or a source link onto a card to append it after a blank line. When editing a card, drop or paste at the textarea caret; selected text is replaced. The edit remains a draft until you use the normal save action. Arbor copies the provided content without cutting or editing the original source. Generated source links are retained with imported Markdown; plain text does not gain a citation automatically.

Use Paste content into card from a card's actions menu (including the mobile block-actions menu), or run Paste content into card from the Command Palette for the currently selected Arbor card. It has no default hotkey. Output Preview and empty background are not targets. If clipboard access is denied, Arbor opens the original card editor so you can use the system Paste command; the current draft is kept.

To create a block instead, drag text or a source reference over a card: two dashed targets appear beside it. New block beside creates a sibling at the same level; New child block adds it inside that branch. Drop onto the card itself to append as before. These targets work in both Branch Editor and Tree Overview, including vertical layouts.

You can also drop an image file onto a rendered card or either new-block target. New files are saved to Obsidian's configured attachment location; an existing image dragged from the vault is embedded without copying it.

Raw binary payloads, HTML-only content, and full Arbor documents are not imported as card text. Supported Obsidian file/link drags can insert a reference; images keep their existing editor attachment path. For cross-folder references, use a reader-generated link or copy a Markdown link; ambiguous raw relative links are not guaranteed to resolve. If a failed import leaves incoming content available, Retry and Copy are view-local for the current view session, not disk or crash recovery. Copy it before reloading if you need to preserve it. Native text Undo depends on the host's edit-history support.

Mobile controls

On a phone, Arbor keeps the selected block's sibling column on screen and puts navigation in a bottom action bar. Tap a card to select it; double-tap a card or use Edit to edit it. Save and Cancel are always visible while editing. Plain Enter makes a new line, while Ctrl/Cmd + Enter on a hardware keyboard saves. Pinch with two fingers in the branch editor to adjust card and text density without leaving the active sibling column.

In Tree Overview, drag with one finger to pan and pinch with two fingers to zoom. A drag never opens a card editor. Use Return to branch editor in the view menu to switch back.

Support

If Arbor is useful to you, you can support development here:

• Buy Me a Coffee

Built-In View Shortcuts

These work inside Arbor itself. They are not command-palette bindings.

Navigation

Editing

Structural creation

Notes:

• The tables describe horizontal Left to right layout. In horizontal Right to left, horizontal arrows and Ctrl/Cmd + horizontal-arrow creation mirror visually: ArrowLeft selects a child and ArrowRight selects the parent. Vertical Tree Overview uses the mappings below.
• The parent-direction creation shortcut is intentionally conservative and does nothing when the selected block is already at the root level.
• Arbor uses event.code for view-level shortcuts where needed, so layout-dependent bindings like search remain stable across keyboard layouts.
• Delete subtree shows a confirmation modal. Normal Delete block does not.

Search and zoom

Tree overview

Use Tree overview from the view menu or Command Palette to see every block in one connected map. Drag empty space to pan; Ctrl/Cmd + mouse wheel changes zoom. Cards render normal Obsidian Markdown and grow to fit their content. Select a card, then press Enter or double-click it to edit directly in place; Arbor smoothly reveals the editor when it is outside the viewport. Export the whole map as a PNG or one-page PDF from the overview menu. Overview always shows collapsed descendants and does not support drag-and-drop reparenting.

Set Tree overview layout in Arbor settings to Horizontal (the default), Vertical — root at bottom (children grow upward), or Vertical — root at top (children grow downward). The same choices in the view menu save the layout for the current note. Notes without their own choice follow the plugin setting.

The note's layout is stored in its hidden Arbor metadata, so it survives closing the tab, restarting Obsidian, renaming the note and syncing it to another device. It applies to every tab showing that note, independently of other notes and Output Profiles. Changing orientation preserves the Markdown body, an active editor draft and content undo/redo history. Return to branch editor keeps Branch Editor horizontal.

Layout direction still controls left-to-right or right-to-left sibling order: in vertical right-to-left mode, previous/next sibling arrows swap, but parent/child remain vertical. Ctrl/Cmd plus a direction arrow creates in that direction: child along the child arrow, sibling along previous/next, or a parent-level sibling along the parent arrow. Home/End shortcuts are Branch Editor-only; number keys select a numbered child (0 selects the parent). The touch dock keeps its Parent/Previous/Next/Child actions with arrows matching the effective layout; its add menu still creates a child or next sibling. PNG and one-page PDF exports use the current Overview orientation and sibling direction, with upright text.

Command Palette Actions

All of these are exposed as normal Obsidian commands. By default, they have no bound hotkey unless you bind one yourself in Obsidian.

View Menu

Arbor includes a compact view menu in its toolbar. The adjacent profile pill switches Output Profiles or opens Manage output profiles….

Use the view menu to:

• search blocks, zoom in/out, or reset zoom to 100%
• switch between Tree Overview and Branch Editor
• save a horizontal, upward, or downward Tree Overview layout for this note
• open Output preview
• export a clean Markdown copy or the tree as PNG/PDF
• open the source note in Markdown
• toggle Selected block panel
• toggle breadcrumb path
• toggle breadcrumb flow
• toggle Ctrl/Cmd + wheel zoom
• open Arbor settings

For Card color…, Branch color…, or Copy block link, open a card's block-actions menu.

Settings

How Notes Stay Normal Markdown

Arbor does not move your note into a database or sidecar file.

Each Arbor note contains:

• the visible Markdown body
• machine-written block markers before each block in the visible body
• an optional %% arbor:output comment for custom Output Profiles
• one readable structure footer at the end of the same note; structure-v2 may also include optional source-location evidence

Minimal compatible note shape (optional source-location evidence is omitted):

<!-- arbor:block:v1 id="root-1" parent="" order="0" -->
# A visible markdown note

This text is still readable in normal Obsidian.

%% arbor:structure
```json
{
  "arbor-plugin": "tree",
  "version": 2,
  "blocks": [{ "id": "root-1", "parent": null, "order": 0 }]
}
```
%%

Important behavior:

• frontmatter is preserved
• the visible body stays readable if the plugin is disabled
• Arbor keeps stable block IDs in both visible markers and the readable structure footer
• optional sourceMap evidence records body ranges and a fingerprint, not a second copy of note content or a sidecar; visible Markdown remains the source of text
• when evidence is stale, unambiguous visible markers can still be reconciled; if marker boundaries are ambiguous, Arbor refuses to guess
• if you open an older Arbor note without visible markers, Arbor upgrades it automatically to the precise marker format
• older plugin versions ignore optional evidence. A downgrade is not guaranteed to preserve notes whose content makes visible marker boundaries ambiguous (for example, literal markers or unfinished code fences); make a clean copy before opening such a note with an older version

Beautiful blocks in the > [!note] style are still normal Markdown callouts. In the screenshots and demo notes, that styling comes from Callout Manager.

Privacy and disclosures

• No account is required.
• No telemetry is collected.
• No ads are shown.
• Arbor does not make network requests for its core functionality.
• Arbor stores plugin settings with Obsidian's plugin data system.
• Arbor stores branch structure inside the note itself as a readable Obsidian comment footer.
• If you paste an image into a block, Arbor writes that image into your vault as a normal attachment.

Demo Notes

Arbor ships with a built-in demo note generator.

Use the command palette action:

• Create demo note

The command creates a new Arbor-managed demo note in the current note folder, or in the vault root if there is no active note.

Compatibility

• Desktop, Android, and iOS
• Obsidian >= 1.7.2
• Plugin ID: arbor
• Latest release and changelog

Known Limitations

• Plain-Markdown rebuild is conservative by design. It protects content first and structure second.
• Undo and redo are Arbor view history, not native editor history.
• Very large notes can still benefit from future virtualization work.
• Mobile Tree Overview exports are capped at 4,096 px on a side and 8 MP before rendering, to avoid unsafe raster allocations.
• Vertical layouts are available in Tree Overview only; Branch Editor remains horizontal.

Feedback and feature requests

Report bugs or suggest improvements in GitHub Issues. Check existing issues first; for a bug, include your Obsidian and Arbor versions, device/platform, and steps to reproduce it.

Development

Contributor workflow:

npm install
npm run dev

Release checks:

npm run lint
npm run build
npm test

Arbor includes a local eslint-plugin-obsidianmd setup so the same reviewer-facing checks can be run before submission updates.

Also check editing, keyboard navigation, links, drag-and-drop, zoom and exports in both views on desktop and mobile before a release.

Repository Layout

arbor/
  assets/
  demo/
  src/
    model/
    storage/
    view/
  tests/
  manifest.json
  package.json
  styles.css