🛣️ Obsidian Hierarchy 🛤️

The Hierarchy Plugin for Obsidian enhances your note-taking experience by visualizing the folder hierarchy of your markdown files directly within the editor. This plugin allows users to see subdirectory structures and modify how file titles are displayed in tabs and backlinks based on their file paths.

📸

Features

• Hierarchy View in Editor: Display the folder structure of the current file in a collapsible hierarchy view within the editor. This provides a clear visual representation of subdirectories and related files.
• Tab Title Customization: Customize the titles of your open tabs. Choose between displaying the full path or just the file name.
• Backlink Title Customization: Modify the way backlink titles are shown by either displaying the full path or only the file name.

Usage

Once installed, the Hierarchy Plugin will:

• Automatically display a hierarchy view when you open a markdown file.
• Update the titles of your open tabs and backlinks to reflect the file path settings.

To configure the plugin:

1. Go to Settings > Hierarchy Plugin.
2. Toggle the settings to enable or disable the hierarchy view, tab title customization, and backlink title customization.

Settings

• Display hierarchy in backlinks panel: Toggle this setting to show the folder hierarchy of files in the backlinks panel, providing more context for each backlink.
• Display hierarchy in tab headers: Enable this setting to show the folder hierarchy in the tab headers, allowing you to see the file's path in addition to its name.
• Display hierarchy in editor view: Enable this setting to display the folder hierarchy below each markdown editor, helping you to quickly see related files in the same directory.
• Use Obsidian's new-note folder: Enabled by default. Omit the default location for new notes from editor hierarchy labels. This follows Obsidian's setting for a specified folder, the current note's folder, or the vault root; the vault root leaves paths unchanged.
• Hierarchy Clean Path Prefixes: Turn off the option above to use custom prefixes, one per line. An empty list keeps full paths. Existing custom lists are preserved on upgrade; the old pages/ default adopts Obsidian's folder setting.
• Hierarchy Exclude Paths: Match an exact path and its descendants, using either the displayed path or the full vault-relative path. For example, Topic/Child also excludes Topic/Child/Leaf, but keeps Topic/Childish. A trailing slash is optional. A full file path such as pages/Topic/Child.md excludes just that note.

Shortened labels always retain their original file destinations. Clicking an item opens that exact note, even if another folder has a note with the same name. Clicking a missing ancestor creates an empty note at its full hierarchy path. Cmd/Ctrl-click and middle-click follow Obsidian's new-tab behavior.

Each editor retains its hierarchy expansion state during refreshes and editor DOM replacement. Closing an editor or unloading the plugin releases its React root. Backlink settings apply immediately to already displayed linked and unlinked mentions; disabling the setting or unloading the plugin restores their original titles while preserving later edits by other plugins.

Open hierarchies refresh when notes are created, renamed, or deleted. Backlink titles preserve dots in folder and file names and omit only the final file extension.

Tips

If you prefer using paths over tags (like I do), I recommend using Obsidian Linter.
When you use Obsidian's autocomplete feature to insert paths, it often automatically adds aliases to the links. You can prevent this by using the following regular expressions:

• Regex to find: \[\[([^\|\[\n]+)\|([^\|\[\n]+)\]\]
• flags: gm
• Regex to replace: [[$1]]

Additionally, I store all my pages under the pages/ directory, but I don’t want to start every link with pages/. To avoid this, I use the following setting:

• Regex to find: \[\[pages/([^\|\[\n]+)\]\]
• flags: gm
• Regex to replace: [[$1]]

This setup will clean up both aliases and the pages/ prefix, leaving a simple and clean path for your links.

ref. https://platers.github.io/obsidian-linter/settings/custom-rules/#custom-regex-replacements

Dev

Run the development checks with:

npm test
npm run build
npm run lint

The tests use Node's built-in test runner and the existing esbuild dependency. Backlink tests run the actual patching code and monkey-around, replacing only Obsidian's runtime classes. Hierarchy tests replace the React DOM host while exercising real JSX, path selection, navigation, settings migration, and static HTML output. Visual behavior and click handling should also be checked in Obsidian.

To bump the version, run npm version patch or npm version minor or npm version major. This will bump the version in package.json, create a new git tag, and push the changes to the repository.

Contributing

Contributions are welcome! If you have ideas, feature requests, or bug reports, feel free to open an issue or submit a pull request.

Thanks

Some code around the backlinks are inspired by the Owner avatar better-search-views .

License

This plugin is open-source and available under the MIT License.