README file from
GithubAccordion 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)
- Install and enable BRAT.
- Run BRAT: Add a beta plugin for testing and enter
stevemclin/accordion-headings. - 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-maskis 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.