README file from
GithubNexusGraph
(3D & 2D Vocabulary & Mind Map Plugin for Obsidian)
NexusGraph is an immersive, interactive spatial graph plugin for Obsidian that transforms your markdown notes into dynamic, interconnected 3D and 2D node networks. Originally built for advanced language learning and vocabulary organization, it scales effortlessly into a general-purpose mind-mapping tool for any topic or project.
🌟 Key Features
- 🚀 Dual-Mode Engine: Instantly toggle between an immersive 3D Force-Directed Graph (with depth-of-field blur and spatial z-index ordering) and a flat 2D Physics Network (
vis-network) with a single click. - 📁 Dynamic Folder & Topic Scoping: Automatically scans your vault's folders and extracts explicit
[topic::]tags to filter your views on the fly. - 🎯 Rich Markdown Tagging: Organize hierarchical knowledge naturally using inline tags (
[topic::],[sub::],[vocab::], and floating badges[n::]). - 🖱️ Actionable & Interactive:
- Smooth node dragging for both parents and sub-nodes with zero simulation bounce-back.
- Click-to-Navigate: Clicking any leaf vocabulary node opens the exact source file and jumps straight to the corresponding line.
- 🎨 20 Vibrant Branch Palettes: Automatically color-hashes your branches across 20 distinct visual palettes paired with dark, clean leaf nodes (
#17202A). - ↻ Live Refresh: Manually re-indexes your vault instantly whenever you add or modify entries.
- 🌓 Adaptive Obsidian Theme & Style Settings: Dynamically reads active Obsidian theme variables and
styles.cssclasses (including Style Settings color overrides) across both light and dark modes—and across 3D and 2D views—without hardcoded inline styles. - 📌 Persistent Pinning: Pin your preferred Folder, Topic, and View Mode (3D/2D) across sessions, with automatic sync when pinning a topic or clearing stale topic pins when switching or unpinning folders.
📸 Demo Figures

📝 Markdown Tag Syntax
NexusGraph parses inline tags separated by backslashes (\) to build your knowledge hierarchy.
You can tag your vocabularies in many files or wherever you like, then your vocabulares are gathered under the same topic and built a mindmap.
Example Note Structure:
- A vocabulary assigned to a topic
[vocab::kündigen]- to quit[topic::[[Common Actions]]]
- A vocabulary assigned to 2 topics, separated by a backslash (
\)
[vocab::sich um (A) kümmern]- to take care of / to look after[topic::[[Common Actions]]]\[sub::Family][topic::[[Relationships]]]
- A vocabulary with a badge
[vocab::kriegen]-[n::informal]to get or receive ~ bekommen or ~ erhalten[topic::[[Common Actions]]]
Note: You can also download the DataView plugin to get the theme treatment for those tags. DataView is also a really great plugin to run JavaScript code inside your note.
Supported Tag Types:
[topic:: Name]: Defines the core central node of the graph.[sub:: Name]: Creates intermediate branch categories and sub-levels.[vocab:: Name]: Represents the leaf nodes (the items you are tracking/studying). Clicking these navigates directly to their source file.[n:: Badge]: Adds a vibrant floating badge pill (e.g.,noun,verb,phrase) to your vocabulary nodes.
🎮 How to Use
- Open the Command Palette (
Ctrl/Cmd + P) and runOpen Vocabulary Graph, or click the network icon in your left ribbon bar. - Select your target Folder from the top-left dropdown.
- Select your desired Topic from the adjacent dropdown.
- Use the
Mode: 3D 🌐 / 2D 🗺️button to switch visualization styles. - Click
↻ Refreshat any time to reload new notes or updates from your vault.
📦 Installation
Manual Installation
- Download
main.js,manifest.json, andstyles.cssfrom the latest GitHub Release. - Create a folder named
nexus-graphinside your vault's plugins directory:<YourVault>/.obsidian/plugins/nexus-graph/. - Drop the downloaded files into that folder.
- Restart Obsidian, go to Settings → Community Plugins, and enable NexusGraph.
📄 License
Distributed under the MIT License. See LICENSE for more information.