Chapter Pipeline
zemengzhou1k downloadsMinimalist Linear-style floating horizontal dash stepper with KaTeX formula preview and pinned top navigation.
- Overview
- Scorecard
- Updates12
🪐 Chapter Pipeline
Minimalist Linear-style outline navigation for Obsidian
Floating heading dashes · KaTeX previews · pinned-top navigation · reading bookmarks
English · 简体中文
Overview
Chapter Pipeline turns long Obsidian notes into a compact, margin-mounted navigation rail. Instead of a permanent outline sidebar, headings are represented as lightweight horizontal dashes beside the note. Hover a dash to preview the section, including KaTeX math; click it to jump to the heading and keep it pinned near the top of the viewport.
It is designed for long technical notes, research documents, study material, documentation, and any workflow where you want fast chapter navigation without giving up screen space.
What's new in 1.2.5
- Full TypeScript runtime architecture — completes retirement of the legacy runtime coordinator, unifying runtime lifecycle, view sessions, and event management under strongly-typed TypeScript modules.
- Obsidian review hardening — resolves community review findings including tooltip lifecycle cleanup, settings reactivity, CSS class naming standards, and strict API safety.
- CodeQL & security hardening — replaces regular-expression parsing with index-based scanners, eliminates innerHTML risks, and ensures clean resource disposal across Obsidian view transitions.
- Performance & resilience — hardened scroll tracking, CodeMirror 6 viewport baseline synchronization, and robust bookmark identity persistence.
See Releases for the full version history.
Core features
Minimal outline rail
- Floating horizontal dashes represent
H1–H6headings without a bulky sidebar. - Heading levels use different lengths and weights for immediate hierarchy recognition.
- Dock the rail on either the left or right margin.
- Automatically hide it in narrow panes so split-screen layouts stay clean.
Hierarchy and progress
Three display modes are available:
- Focus Mode — deeper headings stay folded until the rail is hovered.
- All Headings — show every heading up to the configured maximum level.
- Active Branch Only — expand only the branch around the section currently being read.
An optional vertical progress rail and active indicator make the current position visible without turning the UI into a full minimap.
KaTeX hover previews
- Hover or keyboard-focus a dash to open a compact chapter card.
- Preview the heading plus a short excerpt from the section.
- Inline and multiline LaTeX are rendered with Obsidian's KaTeX pipeline.
- Excerpt truncation preserves math delimiters and multiline formula row breaks.
Pinned-top navigation
Clicking a chapter works in both:
- Reading View
- Live Preview / Source Editing View
Navigation uses calibrated scrolling so the destination heading settles consistently near the top of the active pane, including notes affected by Obsidian's lazy rendering.
Chapter palette and keyboard navigation
Use the command palette to search and jump between chapters, or bind shortcuts for previous/next chapter navigation. The chapter palette supports hierarchy badges, formula previews, and filters for heading level and bookmarks.
Reading progress and bookmarks
Optional local-only reading state can store:
- the last chapter you were reading;
- Revisit markers;
- Important markers.
This data stays in plugin storage. Chapter Pipeline does not modify your Markdown or Frontmatter, and deleted-note records can be cleaned automatically or manually.
Tactile interaction
A lightweight Web Audio synthesizer can provide subtle micro-switch feedback when navigating or crossing chapter boundaries. Sound can be disabled or adjusted in Settings.
Installation
Chapter Pipeline is being prepared for Obsidian Community Plugins. Until it is approved there, use BRAT or a manual GitHub Release install.
BRAT
- Install and enable BRAT from Obsidian Community Plugins.
- In BRAT, choose Add Beta plugin.
- Enter
dreamfarer-space/obsidian-chapter-pipelineand add the plugin. - Enable Chapter Pipeline under Settings → Community Plugins.
Manual installation
- Download
chapter-pipeline-<version>.zipfrom the latest GitHub Release, or downloadmain.js,manifest.json, andstyles.cssseparately. - Place the three plugin files in:
<YourVault>/.obsidian/plugins/chapter-pipeline/
- Reload Obsidian and enable Chapter Pipeline under Settings → Community Plugins.
Commands
All commands can be assigned custom hotkeys in Settings → Hotkeys.
| Command | Purpose |
|---|---|
Chapter Pipeline: Jump to previous chapter |
Jump to the previous heading. |
Chapter Pipeline: Jump to next chapter |
Jump to the next heading. |
Chapter Pipeline: Search & switch chapter |
Open the fuzzy chapter palette. |
Chapter Pipeline: Resume last chapter |
Return to the locally saved reading position. |
Chapter Pipeline: Toggle revisit bookmark for current chapter |
Toggle a Revisit marker. |
Chapter Pipeline: Toggle important bookmark for current chapter |
Toggle an Important marker. |
Chapter Pipeline: Clear reading progress & bookmarks for current note |
Remove local reading state for the active note. |
Chapter Pipeline: Clean up invalid reading progress & bookmarks |
Remove stale records for deleted or moved notes. |
Settings
Show settings reference
| Setting | Default | Description |
|---|---|---|
| Show excerpt preview | On | Show a short section excerpt in the hover card. |
| Ignore first H1 | Off | Skip the note-title H1 when building the rail. |
| Dock position | Left | Place the rail on the left or right margin. |
| Heading hierarchy mode | Focus Mode | Choose Focus, All Headings, or Active Branch Only. |
| Show vertical progress rail | Off | Display the reading-position guide. |
| Reading progress & bookmarks | Off | Store local resume points and chapter markers. |
| Tooltip glassmorphism | On | Enable backdrop blur and spring-style tooltip motion. |
| Max heading level | H2 | Limit which heading levels appear in the rail. |
| Active indicator color | Azure | Select a preset, theme accent, or custom color. |
| Narrow-view auto-hide threshold | 600 px | Hide the rail below the configured pane width. |
| Tactile sound | On | Enable synthesized interaction sounds. |
| Sound volume | 50% | Set tactile feedback volume. |
Performance and accessibility
Chapter Pipeline is built to keep per-frame work small on large documents:
- passive,
requestAnimationFrame-coalesced scroll handling; - cached Reading View heading resolution;
- cached Live Preview chapter candidates;
- incremental or binary-search active chapter lookup;
- mutation filtering so irrelevant editor DOM changes do not rebuild caches;
- bounded parsing caches and deterministic listener/resource cleanup.
The UI also supports keyboard focus, screen-reader semantics, reduced-motion preferences, forced-colors mode, touch-friendly tooltip behavior, and contrast-aware active indicators.
Development
The plugin source is TypeScript under src/, bundled to the committed CommonJS main.js entry point used by Obsidian.
npm ci
npm run build
npm test
npx --no-install tsc --noEmit
Repository CI additionally verifies that a production build does not leave an uncommitted main.js diff.
Architecture and implementation notes live in docs/:
PHASE1_MIGRATION.md— typed module migration boundaryPHASE2_PERFORMANCE.md— performance workPHASE3_COMPLIANCE_AUDIT.md— compliance and lifecycle auditPHASE4_UI_UX.md— UI/UX, motion, touch, and accessibility notesCOMMUNITY_SUBMISSION.md— authoritative current release/platform state and compatibility evidence
Compatibility verification
The current 1.2.5 manifest declares minAppVersion: 1.8.7 and isDesktopOnly: true. The latest recorded real-app smoke matrix was run on the packaged 1.2.5 build on 2026-09-26 and passed on official Obsidian Desktop 1.8.7 and 1.13.7. See docs/COMMUNITY_SUBMISSION.md for the exact evidence. Android/iOS support is not currently claimed.
Privacy
Chapter Pipeline does not require an external service. Reading progress and bookmarks are stored locally by Obsidian's plugin data API and are disabled by default.