Accordion Headings

by Stephen Mclin
5
4
3
2
1
Score: 50/100

Description

Website-style accordion folding for Obsidian headings: one rotating chevron, full-row click target, in Reading, Live Preview and Source views.

Reviews

No reviews yet.

Stats

0
stars
76
downloads
0
forks
5
days
3
days
3
days
1
total PRs
0
open PRs
0
closed PRs
1
merged PRs
0
total issues
0
open issues
0
closed issues
12
commits

Latest Version

4 days ago

Changelog

Fixes the caret bug reported on desktop and mobile.

What was wrong

The chevron is a CodeMirror inline widget sitting at the end of the heading line. Because it had real inline width, a caret at that same position was drawn on the far side of the icon: typing landed at the end of the heading while the cursor appeared somewhere else. A second problem made it worse — any click at or past the end of the heading text folded the section, stealing the natural "click after the last word to keep typing" gesture.

What changed

  • The chevron no longer takes layout space. It is now a zero-width box with the icon positioned inside it, so the caret always lands at the true end of the text. The icon stays visible the whole time — nothing is hidden while you edit.
  • The end of a heading stays editable. Clicks in the small gap after the last character place the caret; the icon itself still folds, as does the empty area further right.
  • Folding is untouched otherwise: same fold state, same Outline sync, same settings.

Under the hood

  • Editor logic moved to src/editor.ts, free of any obsidian import, with Obsidian's createSpan injected. Same shipped code, now testable outside Obsidian.
  • A behaviour harness (test/) mounts that extension in plain CodeMirror 6 against the shipped styles.css and asserts 14 behaviours — caret position relative to the icon, click zones, fold toggling, disabled levels, settings rebuilds.
  • npm test builds the harness and runs it headless; .github/workflows/ci.yml gates every pull request on it.

Requires Obsidian 1.5.0 or later.

README file from

Github

Accordion Headings

Website-style accordion folding for Obsidian headings. One chevron that stays in the same place in both states, and a full-width heading row you can click anywhere.

Obsidian's built-in heading fold puts a chevron on the left that disappears when the section is expanded, plus a separate … on the right when it is collapsed: two affordances for one control, in two different places. This plugin replaces that with the standard accordion pattern used across the web:

  • One chevron, inline after the heading text — right where the … used to be.
  • The same control in both states. It rotates in place: ▾ expanded, ▸ collapsed. Nothing appears or disappears.
  • Full-row click target. In Reading view the whole heading row clicks. In Live Preview and Source the empty area to the right of the heading clicks, while the heading text itself stays editable.
  • Configurable — icon style, visibility, and which heading levels are affected.

Install

Community plugins

Once the plugin is listed in the directory: Settings → Community plugins → Browse, search for Accordion Headings, install, enable.

Beta (via BRAT)

  1. Install and enable BRAT.
  2. Run BRAT: Add a beta plugin for testing and enter stevemclin/accordion-headings.
  3. Enable Accordion Headings in Settings → Community plugins.

Manual

Download main.js, manifest.json, and styles.css from the latest release and copy them into <your-vault>/.obsidian/plugins/accordion-headings/. Then enable the plugin in Settings → Community plugins.

Settings

Setting Options Default
Icon style Chevron, Plus / minus Chevron
Visibility Always visible, On hover Always visible
Heading levels H1 – H6, one toggle each All enabled

How it works

The plugin does not implement folding. It drives Obsidian's own fold state and changes only the visual affordance, so the Outline panel and Fold all / Unfold all stay in sync — there is a single source of truth for whether a section is collapsed.

Mode Mechanism
Reading view Obsidian already renders a .heading-collapse-indicator inside each heading that owns the fold click. The plugin stretches that hit area to cover the whole row, hides its default icon, and draws the indicator on the heading's ::after as an SVG mask, so it stays crisp and picks up the theme's text colour. Collapsed state is read from the is-collapsed class Obsidian sets on the heading's section container.
Live Preview / Source A CodeMirror 6 ViewPlugin places a chevron widget at the end of each heading line. Toggling reads the section range from @codemirror/language's foldable(), tests it against foldedRanges(), then dispatches foldEffect or unfoldEffect — the same fold state Obsidian's own .cm-fold-indicator writes.

All styling lives in styles.css — the plugin never injects CSS. Your settings are applied by toggling classes on <body> (ah-h1…ah-h6, ah-icon-plus, ah-vis-hover), so a change takes effect immediately without a reload.

Limitations

  • ATX headings only (#–######). Setext headings (=== / --- underlines) keep Obsidian's default behaviour.
  • Live Preview: clicking the heading text places the cursor instead of folding. This is deliberate — the plugin lives inside an editor, and stealing text clicks would make headings awkward to edit. Use the chevron, or the empty space to its right.
  • The end of a heading stays editable. Clicking just after the last character places the caret rather than folding; only clicks further right, or on the chevron itself, fold the section. The chevron also sits in a zero-width box in Live Preview, so it never takes up layout space and never draws the caret to the wrong side of the text you are typing.
  • Reading view draws its indicator with a CSS mask. -webkit-mask is supported by every Chromium that ships in Obsidian 1.5.0 and later, which is this plugin's minimum, so the icons render on every version it installs on.

Development

npm install
npm run build                                        # typecheck + bundle main.js
npm test                                             # behaviour harness, headless
OBSIDIAN_VAULT="/path/to/your/vault" npm run deploy  # copy build into a test vault

Testing

npm test builds test/index.html and runs it in headless Chrome (or Edge, or $CHROME_PATH). The harness mounts the real editor extension from src/editor.ts in plain CodeMirror 6 against the shipped styles.css and asserts the behaviour that is easy to break: the chevron must not displace the caret, clicks in the gap after a heading must place the caret, clicks further right and on the icon must fold, disabled levels must render nothing, and a settings change must rebuild open editors.

Run npm run test:build and open test/index.html to see the same checks in a browser, which is the fastest way to inspect a failure.

Branch workflow

master is release-only. Work on a branch, let CI verify it, merge, then tag:

git checkout -b fix/something
npm test                 # or rely on the PR check
git push -u origin fix/something
gh pr create --fill

.github/workflows/ci.yml runs the typecheck, the build and the harness on every pull request and on pushes to non-master branches. Merging to master does not publish anything by itself — .github/workflows/release.yml only cuts a release when a version tag is pushed, and it refuses to build if the tag and manifest.json disagree.

main.js is a build artifact and is not committed.

License

MIT