Node Tree Graph

Visualize your vault as a hierarchical heading-based graph. Break notes into granular nodes based on their internal heading structure.

📌 User Guides

Core Concepts

By default, Obsidian’s built-in graph view treats each .md file as a single node. This plugin breaks down your markdown documents into a hierarchical node tree:

1. Root Node: The markdown file itself (just like Obsidian’s default graph).
2. Leaf Nodes: Level $N$ headings ($H_1$ to $H_6$) inside the file, representing sub-topics and sections.

This gives you control over how granular your graph visualization can be, allowing you to trace connections between specific sections of different notes without losing context.

Key Features

1. Max Heading Levels: Choose how deep the graph searches (from $H_1$ up to $H_6$).
2. Flexible Link Rollup: When headings are hidden, links associated with those hidden sections can automatically roll up to the nearest visible ancestor node or be cleanly discarded.
3. Hover Filtering: Highlight related nodes when hovering:
   1. Neighbor Direction: Search Downward (children), Upward (parents), or Both.
   2. Neighbor Depth: Limit how many connections away the search reaches.
4. Fully customizable Visuals & Physics.
   1. Nodes: coloring mode, base node radius, and relative scales for ($H_1$ to $H_6$).
   2. Edges: width, color, style, and alpha.
   3. Font: font family, size, color, option to scale with node size, and size multiplier.
   4. Physics: simulation related settings.

Example

The following example is created using a obsidian-test-vault.

Installation

From the Community Plugin Directory

1. Open Obsidian → Settings → Community plugins
2. Search for Node Tree Graph
3. Click Install, then Enable

Manual Installation

1. Download main.js, manifest.json, and styles.css from the latest release
2. Copy them into {vault}/.obsidian/plugins/node-tree-graph/
3. Enable the plugin in Settings → Community plugins

Search Filter Syntax

The search input in the Filters section follows Obsidian's official search syntax to filter which file trees appear in the graph:

Examples

Autocomplete suggestions appear automatically when typing tag:, file:, path:, or [.

Developer Guides

Project Structure

src/
├── main.ts                     # Plugin entry point
├── settings.ts                 # PluginSettingTab + DEFAULT_SETTINGS
├── types.ts                    # TypeScript type definitions
├── ui/
│   ├── graph-view.ts           # ItemView (graph pane)
│   ├── graph-renderer.ts       # PixiJS renderer + simulation
│   ├── popup-panel.ts          # Settings/filter popup overlay
│   ├── node-sprites.ts         # Node shape + label creation
│   ├── physics.ts              # Force-directed simulation
│   ├── search-autocomplete.ts  # Autocomplete for search filters
│   ├── control-panel.ts        # Sidebar control panel (stub)
│   ├── debug-overlay.ts        # Performance metrics overlay (stub)
│   ├── legend.ts               # Mini legend (stub)
│   └── onboarding.ts           # First-run onboarding (stub)
├── utils/
│   ├── tree-manager.ts         # Cache + tree→graph conversion + search filter
│   ├── parser.ts               # Markdown → NodeTree parser
│   ├── cache.ts                # LRU cache manager
│   ├── colors.ts               # Color resolution
│   ├── shapes.ts               # Shape resolution
│   ├── sanitize.ts             # Label formatting
│   ├── constants.ts            # Plugin constants
│   └── rollup.ts               # Link rollup logic
└── commands/
    └── index.ts                # Command palette commands

Components

1. Settings panel.
2. Popup panel: the popup panel by clicking the gear icon from canvas.
   1. Tooltip panel: the popup panel when typing in search input box.

How It Works

1. Parser (src/utils/parser.ts): Each markdown file is parsed into a NodeTree: headings form the hierarchy, wiki links and embeds are assigned to their owning heading block based on line position. Frontmatter properties and tags are extracted.
2. Tree Manager (src/utils/tree-manager.ts): Maintains an LRU cache of parsed trees, listens for vault metadata changes, and regenerates graph nodes and edges on demand. The search filter operates at this level — excluded trees never become graph nodes.
3. Graph Renderer (src/ui/graph-renderer.ts): PixiJS WebGL renderer draws nodes as colored geometric shapes with text labels, connected by tree edges (parent→child) and link edges (wiki links). Node visibility is driven by the pipeline: orphan/file-level filtering → tag/attachment toggles → hover dimming.
4. Force Simulation (src/ui/physics.ts): Semi-implicit Euler integration with many-body repulsion, spring attraction, centering force, tree separation multiplier, and simulated annealing (alpha decay).

Development Build

git clone https://github.com/zhengyuan-public/obsidian-node-tree-graph.git
cd obsidian-node-tree-graph
npm install
npm run build

Then symlink or copy the repo into your vault's .obsidian/plugins/ directory.

Localization (i18n)

Node Tree Graph supports multiple languages. The interface language is automatically detected from your Obsidian settings.

Supported languages:

Contributing translations

The initial translations were translated by AI from English and may contain inaccuracies. If you're a native speaker of any of these languages, we'd love your help improving them! To contribute:

1. Copy src/i18n/en.ts as a reference for all available keys
2. Edit the translation file for your language in src/i18n/<code>.ts
3. Submit a pull request with your changes

New languages are also welcome, just create a new file following the same format and register it in src/i18n/index.ts.

Adding a new language:

// src/i18n/it.ts
const it: Record<string, string> = {
  'view.display-name': 'Grafo ad Albero',
  'filter.tags': 'Etichette',
  // ...translate all keys from en.ts
};
export default it;

Then register it in index.ts:

import it from './it';
const locales = { ..., it };

Tech Stack

• Obsidian Plugin API
• PixiJS v8
• TypeScript
• Vitest
• esbuild

Known Issues & Roadmap

Needs Fixing

Not Yet Implemented