# 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.

```text
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

![List Static Tree Indentation Guides](screenshots/List%20Static%20Tree%20Indentation%20Guides%20-%20List%20Tree%20Indentation%20Guides%20Plugin.png)

### Active List Item Threading

![Active List Item Threading](screenshots/Active%20List%20Item%20Threading%20-%20List%20Indentation%20Guides%20Plugin.png)

### Active List Item Threading — Orphan List

![Active List Item Threading - Orphan List](screenshots/Active%20List%20Item%20Threading%20-%20Orphan%20List%20-%20List%20Indentation%20Guides%20Plugin.png)

### All Branches of an Active List Threading

![All Branches of an Active List Threading](screenshots/All%20Branches%20of%20an%20Active%20List%20Threading%20-%20List%20Indentation%20Guides%20Plugin.png)

### All Branches of an Active List Threading — Orphan List

![All Branches of an Active List Threading - Orphan List](screenshots/All%20Branches%20of%20an%20Active%20List%20Threading%20-%20Orphan%20List%20-%20List%20Indentation%20Guides%20Plugin.png)

### List Hover Breadcrumb

![List Hover Breadcrumb](screenshots/List%20Hover%20Breadcrumb%20-%20List%20Tree%20Indentation%20Guides%20Plugin.png)

## 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.

| Setting | Purpose |
| --- | --- |
| List Static Tree Indentation Guides | Globally enables or disables the always-visible tree guides. Enabled by default. |
| Unmarked List Head Static Tree Indentation Guides | Gives the immediately preceding unmarked line its own static guide. Disabled by default. |
| Render in Live Preview | Shows guides in the editable Live Preview view. |
| Render in Source mode | Shows guides alongside raw Markdown list syntax. |
| Render in Reading mode | Shows guides in rendered Markdown. |
| Connect separate list blocks | Lets continuation/gutter spines bridge non-list content between editor list blocks. Disabled by default. |
| List Threading | Enables Logseq-style active-list highlighting. |
| Active Cursor List Threading | In Live Preview and Source mode, replaces hover activation with the focused editor caret for every enabled regular or orphan threading submode. Disabled by default; Reading mode remains hover-based. |
| Active List Item Threading | Highlights the complete ancestor path to the active list item. Enabled by default. |
| Thread separate list blocks that are only separated by a blank line (Active Item) | Lets an active-item path continue into an adjacent blank-line-separated list block. Disabled by default. |
| All Branches of an Active List Threading | Highlights every branch in the active item’s list block. Disabled by default. |
| Thread separate list blocks that are only separated by a blank line (All Branches) | Lets All Branches include adjacent blank-line-separated blocks. Disabled by default; nonblank content always separates threading blocks. |
| Unmarked List Head List Threading | Extends Active Item and All Branches threading from the immediately preceding unmarked line. Enabled by default. |
| Active Orphan List Threading | Enables threading for top-level ordered or unordered list blocks without an unmarked list head. Enabled by default. |
| Active Orphan List Item Threading | Highlights the path to the active item in an orphan list. Enabled by default. |
| All Branches of an Active Orphan List Threading | Highlights every branch in the active orphan list block. Disabled by default. |
| Thread in Live Preview | Allows hover- or caret-activated threading in Live Preview when the global feature is enabled. |
| Thread in Source mode | Allows hover- or caret-activated threading in Source mode when the global feature is enabled. |
| Thread in Reading mode | Allows hover-activated threading in Reading mode when the global feature is enabled. |

### 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.

| Breadcrumb control | Default / behavior |
| --- | --- |
| List Hover Breadcrumb | On; disabling it makes subordinate controls inaccessible. |
| Unmarked List Head Hover Breadcrumb Activation | On; independent of main and breadcrumb threading. |
| Full-Width List Item activation | Off. |
| Full-Width List Marker activation | On. |
| Live Preview, Source, Reading activation | All on, independently configurable. |
| Expand long list items | On; wraps complete labels. Off uses a single line with an ellipsis. |
| List Hover Breadcrumb List Markers | On, with separate marker typography and appearance controls. |
| List Hover Breadcrumb Static Tree Indentation Guides | On; all three modes on, connect-separate-blocks off. |
| List Hover Breadcrumb Threading | Off; independent per-mode controls, active-item and orphan modes, unmarked heads, and blank-line joining mirror the main settings. All-branches threading expands the displayed tree to include the selected block's branches. |
| Active Selected List Threading | Off; when enabled, the current/last clicked row determines popup threading instead of the hovered row. This adapts cursor threading to the popover. |
| Navigate before timeout | On; preview scrolling preserves the editor caret and restores the prior scroll position on cancellation. |
| Navigate after timeout | Off; enabling it retains or applies the last previewed row when the dismissal timer expires. Escape cancels deferred navigation. |
| Popover timeout | Global on at 0.01 seconds, with optional independent decimal overrides for each viewing mode. |

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

```bash
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

```bash
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](docs/validation-2.0.3.md) for baseline failures, the optional Obsidian 1.14.4 parser check, and remaining desktop checks. The [2.0.2 validation notes](docs/validation-2.0.2.md) 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](https://github.com/obsidiest/obsidian-bullet) fork.

The List Hover Breadcrumb interaction, settings, navigation behavior, and appearance controls are adapted from [Extended Headings 2.1.0](https://github.com/obsidiest/obsidian-extended-headings/tree/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