List Tree Indentation Guides

List Tree Indentation Guides renders nested Obsidian lists as a visually connected tree. Each sibling group receives a continuous vertical spine, and each ordered, unordered, or task-list item receives a horizontal connector.

Example
├─ Example
│  ├─ Example
│  ├─ Example
│  │  └─ Example
│  └─ Example
└─ Example
   └─ Example

The implementation is scoped to rendered list items and CodeMirror's visible HyperMD-list-line-N rows. It measures the markers already rendered by Obsidian, coalesces editor updates to animation frames, and never scans the vault.

Feature Preview

With their corresponding toggles enabled:

List Static Tree Indentation Guides

Active List Item Threading

Active List Item Threading — Orphan List

All Branches of an Active List Threading

All Branches of an Active List Threading — Orphan List

List Hover Breadcrumb

Features

• Connected tree guides for ordered, unordered, mixed, and task lists.
• A global static-guide toggle plus independent rendering toggles for Live Preview, Source mode, and Reading mode.
• Separate list blocks remain visually separate across both content and blank-line boundaries by default, with an optional continuation/gutter-spine setting.
• Optional Logseq-style list threading that responds across the full hovered list-item row or, in editor modes, the active caret line.
• A disabled-by-default Active Cursor List Threading override that changes regular and orphan list activation from hover to the focused editor caret in Live Preview and Source mode.
• Independent active-item-path and all-branches threading subfeatures, each with its own optional blank-line block threading.
• Threading from an immediately preceding non-bulleted/numbered list head.
• Dedicated active-item and all-branches threading controls for orphan ordered and unordered list blocks.
• A global threading toggle plus independent Live Preview, Source, and Reading-mode threading toggles.
• Searchable settings, including aliases for common mode names.
• Pop-out-window support.
• Minimal-theme-compatible styling based on Obsidian variables.
• Style Settings customization with exact numeric entry alongside every slider.
• Unordered-list markers are visible by default and can be suppressed from Style Settings.
• Measured static guides and threading inside internal heading and block embeds, with an isolated overlay for each rendered surface.
• List Hover Breadcrumb: a scrollable ancestor tree with clickable source navigation, row previews, keyboard navigation, and independent styling.

Plugin settings

Every plugin setting is searchable from Obsidian's Settings search. List static tree-guide rendering and all three mode preferences are enabled by default. Connecting separate list blocks is disabled by default. List Threading is globally disabled by default; Active List Item Threading, threading from an unmarked list head, Active Orphan List Threading, Active Orphan List Item Threading, and the three mode preferences are enabled so they take effect immediately if the global feature is enabled. Active Cursor List Threading, both all-branches options, and both blank-line list-block options are disabled by default.

List Hover Breadcrumb

The breadcrumb is enabled by default in Live Preview, Source, and Reading mode, including internal embeds. Hover from the left gutter through a list marker to open it. Enable Full-Width List Item List Hover Breadcrumb Activation to activate across the entire row. With both full-width options off, only the marker activates it. Unmarked List Head Hover Breadcrumb Activation is enabled by default and operates independently of threading. Under List Hover Breadcrumb Activation Scope, full-item activation includes the head row; full-marker activation includes only its gutter. With both scopes off, unmarked heads do not activate a breadcrumb because they have no marker. Right-to-left layouts use the corresponding right gutter.

The popover shows the item's ancestors and highlights the current item. Hover or focus another row to preview that field in the main view. Click a row to navigate permanently. In an embed, clicking an ancestor outside the visible excerpt opens its original note at the source line. Repeated labels use source positions to identify the correct item.

Breadcrumb labels use Obsidian's Markdown rendering for LaTeX, SVG, links, and formatting, including multiline content belonging to the item. In Live Preview and Source, paragraph gaps follow empty editor lines at the breadcrumb's text size; in Reading mode, they follow the originating note's paragraph-margin setting. Guides follow individual row-size changes so late wrapping does not leave a branch inside parent text. Footnotes use definitions and reference numbering from the originating note; clicking a footnote opens that note's definition. Links inside a label remain clickable. Each popover releases its render resources when dismissed.

Arrow Up/Down, Home, and End move focus through breadcrumb rows. Enter activates a row; Escape closes the popover. The gap between the source row and the popover remains traversable while the pointer moves between them.

Embed drawings use a clipped layer outside the embedded document so they do not add to its scrollable height. Each nested embed owns its own drawing layer.

The breadcrumb's settings and Style Settings variables are independent of those used in the note. Child controls are disabled whenever their parent feature is disabled. List Threading in rendered embeds uses hover; an embed has no editable caret.

Style Settings

Install and enable the community plugin Style Settings to customize:

• Guide color.
• Guide opacity.
• Guide thickness.
• Horizontal connector length.
• Gap before the list marker or content.
• First-branch vertical rise.
• Connector vertical offset.
• Solid, dashed, or dotted guide pattern.
• Dash and dot spacing.
• Visibility of unordered-list bullets in Live Preview and Reading mode (enabled by default).
• Active-item and all-branches thread opacity, thickness, line caps, and corner radius.
• Thread connector length, Thread connector height, marker gap, and vertical offset.
• Eight independently themed list-thread colors, each with an enabled-by-default toggle; deeper levels reuse the eighth color.
• An enabled-by-default global fallback for disabled list-thread colors and a disabled-by-default global override with independently persisted light- and dark-mode native color inputs.
• Breadcrumb appearance, dimensions, spacing, typography, current/hovered-row highlights, marker styling, static guides, and threading, including separate color enablement, fallback, and override controls.

Thread connector height defaults to 103% in the main view; the independent breadcrumb control defaults to 100%. Threads start from the parent marker, using the visible bullet, numeral text range, or checkbox bounds. Wrapped parent text does not shorten the connector. At 100%, the upper end leaves the configured marker gap and stroke-cap clearance. Lower percentages shorten the upper end of each elbow; they do not move the child's horizontal connector. Values above 100% reduce that gap, stopping when the stroke reaches the parent marker boundary. Increasing the value further cannot draw through or above the marker, including when a distant later child is active. The slider reaches 500%; its precise value field accepts any nonnegative finite percentage, including larger values. Breadcrumb threading has its own height control.

Thread marker gap defaults to 6.5 px in the main view and 4 px in breadcrumbs. Saved values take precedence. Numbered tasks reserve space for both the number and the checkbox. At the default 28 px Thread connector length, a child branch aligns below its parent's primary marker (the numeral for numbered tasks, or the checkbox for unnumbered tasks). Increasing the length moves that spine outward; changing the child's marker type or marker gap no longer moves the parent attachment. Root branches without a marked parent retain their fixed horizontal reach.

Version 2.0.0 measures rendered markers and sibling positions directly. The old Reading-mode row-height, segment-overlap, and marker-position compensation controls are retired; they depended on fixed spacing and caused misalignment in embeds. Existing mode, threading, and color preferences retain their saved keys.

Every numerical Style Settings slider receives a synchronized editable field. Typed in-range decimals are preserved exactly, including transient input such as 1. while editing; invalid or incomplete values revert only when editing finishes.

Paragraph Spacing is under List Hover Breadcrumb → Breadcrumb Geometry and Typography. Turn on Custom paragraph spacing to set the gap between paragraphs within each item, from 0 to 4 em (1em is the item's font size). The slider and precise input appear indented beneath the enabled toggle. The default custom value is 1 em; zero removes the gap. With the toggle off, breadcrumbs continue to follow the originating editor's blank-line spacing or the rendered note's paragraph spacing.

Named footnotes in editor breadcrumbs retain source identifiers such as [^11] and [^2]. Breadcrumbs opened from rendered notes or embeds reuse their displayed footnote labels, including repeat-reference suffixes. When an originating rendered label is unavailable, the source identifier is retained instead of assigning a new number.

Themed colors have separate Light and Dark buttons. Choose a color or enter a hex value, then click Save to persist and apply it. The dialog closes after saving succeeds; a failed save leaves it open with an error. Default fills the declared default for that theme, and Cancel or Escape discards the draft. Existing color preferences retain their Style Settings keys. Saving also repairs malformed hex/non-finite values in this plugin's themed colors that would otherwise prevent Style Settings from generating CSS.

Installation

From a release

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Create <vault>/.obsidian/plugins/list-tree-indentation-guides/.
3. Copy the three files into that folder.
4. Reload Obsidian and enable List Tree Indentation Guides under Community plugins.

Build from source

npm ci
npm run build

Copy main.js, manifest.json, and styles.css into the plugin folder in the vault.

Compatibility

• Requires Obsidian 1.13.0 or newer.
• Supports desktop and mobile.
• Designed to coexist with Minimal theme and its Style Settings controls.

Development checks

npx tsc --noEmit
npm run lint
npm test
npx playwright install chromium
npm run test:browser
npm run build
git diff --exit-code -- main.js

The validation and release workflows run browser layout and interaction tests as well as type, lint, and unit checks. The release workflow confirms that committed main.js is current, creates the three standard Obsidian release assets, and publishes GitHub artifact attestations for each asset.

Browser tests use Chromium, real CodeMirror, and the plugin's actual modules with a minimal Obsidian host adapter. They are not tests inside Obsidian desktop. See 2.0.3 validation notes for baseline failures, the optional Obsidian 1.14.4 parser check, and remaining desktop checks. The 2.0.2 validation notes also describe the optional Style Settings integration check.

Acknowledgements

The list-threading interaction and rendered-list geometry are adapted from the MIT-licensed obsidiest/obsidian-bullet fork.

The List Hover Breadcrumb interaction, settings, navigation behavior, and appearance controls are adapted from Extended Headings 2.1.0, also MIT-licensed (copyright 2026 obsidiest). Heading-level-specific Outline, root/orphan-heading-gap, and mixed-heading-tree controls do not apply to list hierarchies; the list plugin's regular, orphan, and blank-line block modes are used instead.

License

MIT