Breadcrumbs

Breadcrumbs is an Obsidian plugin that adds typed links (e.g., up/down, next/prev) to your notes to build a directed graph. Unlike the standard Obsidian graph which only shows connection existence, Breadcrumbs defines the nature of the relationship.

Key features include:

• Breadcrumb Trail: A navigation path at the top of notes showing ancestors.
• Tree View: A side view showing the hierarchy beneath the current note.
• Matrix View: A view grouping incoming and outgoing relationships by type.
• Navigation Buttons: Previous and Next buttons for sequential note traversal.
• Embedded Diagrams: Use ```breadcrumbs ``` codeblocks to render a note's neighborhood as a Tree, Mermaid diagram, or Markmap mind-map.
• Canvas Export: Export a note's neighborhood as a native Obsidian Canvas with labeled edges.

Graph Builders (formerly known as "Alternative Hierarchies") define the different ways edges are added to the Breadcrumbs graph.

Currently implemented builders include:

• Regular frontmatter links: Using up: [[note]] in YAML.
• Dataview links: Using up:: [[note]].
• Tag notes
• List notes (formerly "Hierarchy notes")
• Dendron notes
• Date notes
• Folder notes
• Regex notes
• Traverse notes

The from field in codeblocks uses Dataview-style queries (e.g., #tag, "folder", [[link]]) to filter or define entry points. The behavior differs depending on the codeblock type:

• Tree and Mermaid: The from match acts as a restrict-filter. The traversal always starts from the source_path (or the resolved entry point), and the query is used to bound which nodes are allowed to appear in the view.
• Markmap: The from match acts as a replacement for the entry point. Instead of starting from the active file, the map is generated by walking from every path that matches the query, creating a 'map-of-everything' view.

Breadcrumbs can derive relationships from several different sources within your Obsidian vault:

• Metadata: Frontmatter properties (typed links), tags, and Markdown lists.
• Naming Schemes: Patterns like Dendron (parent.child), Johnny.Decimal (01.02 Title), dates, or custom regex.
• Structure: Folder-based relationships (folder notes) and Dataview queries.

Breadcrumbs also supports implied relations (e.g., if A is up from B, then B is automatically down from A) and allows for custom transitive rules.

When building custom graph builders, use these two distinct mechanisms for handling field overrides and defaults:

1. read_edge_field: Used for a builder's primary field. It checks for a per-note override (BC-<source>-field), then falls back to a settings default. If the value is invalid, the note is excluded from the build entirely.
2. validate_optional_edge_field: Used for secondary/optional fields (e.g., sibling_field or neighbour_field). It follows the same override-then-default logic, but if the field is unset, it remains unset rather than causing the note to be excluded. Only a present-but-invalid value triggers an error.

Breadcrumbs makes no automatic outbound network requests. The only outbound request is user-initiated when interacting with Mermaid diagrams:

• Mermaid Diagrams: When a user clicks the "View Image on mermaid.ink" button on a rendered Mermaid codeblock, the browser opens https://mermaid.ink/img/<encoded-diagram> in a new tab.
• Data Privacy: The diagram text is base64-encoded using btoa() and appended to the URL. No data is sent to any Breadcrumbs-owned servers.

Note for auditors: Static scans of main.js may flag fetch( calls due to transitive dependencies like KaTeX (which uses a Parser.fetch() method for internal parsing) or markmap-view (which contains a CDN loader that is never reached by Breadcrumbs). These are not active network calls by the plugin.

Breadcrumbs versioning is tied to your Obsidian app version:

• Obsidian 1.13 or later: Use the current version of Breadcrumbs (v4.15.0+). These versions use the declarative settings API and support page-based navigation in settings.
• Obsidian 1.12 or earlier: Use Breadcrumbs 4.14.2. This is the last release supporting the older Obsidian versions. Fixes for this line are maintained on the 1.12-compat branch.

To execute tests in a Node.js environment, use wasm-pack test with the --node flag and enable the test feature.

wasm-pack test --node --features test

The Breadcrumbs graph engine is a WebAssembly binary (wasm/pkg/breadcrumbs_graph_wasm_bg.wasm) written in Rust. To ensure the binary matches the provided Rust source code in wasm/src/, you can perform a reproducible build and compare the output. The binary is embedded directly into main.js at build time and is never fetched from a remote URL.

To rebuild the WASM module from source, use the following command:

bun run wasm:build

V4 introduces several breaking changes. If you are upgrading from a previous version, note the following field and class renames:

Configuration Changes:

• List Notes: Instead of listing all List note names in a single global setting, you must now use the BC-list-note-field frontmatter field within each individual list note.
• Command Renaming: The Refresh Breadcrumbs Index command is now Rebuild graph. Update your hotkeys accordingly.

To build the WebAssembly package for use in web environments, use wasm-pack with the --target web flag. Note that dependencies/packages will be downloaded automatically during the first build execution.

wasm-pack build --target web