Fold by Bullet
Akira HIRATA484 downloadsCollapse list items by default based on the bullet character they use. Write - to start folded and + to stay open.
- Overview
- Scorecard
- Updates5
An Obsidian plugin that decides which list items start folded, based on the bullet character you typed.
- Reference ← starts folded
- RFC 5545
- RFC 3339
+ Today's plan ← stays open
+ Ship the release
+ Review the PR
Markdown treats -, * and + as the same thing, so the choice is normally cosmetic. This plugin gives it a meaning: one character for "detail I rarely need", another for "keep this in front of me".
Why
Long notes accumulate reference material that you want to keep but not look at. Obsidian can fold a list, but the fold is a per-session gesture, not a property of the note. You end up refolding the same sections every time you come back.
Existing solutions ask you to annotate the note — %% fold %% markers, callouts, <details> blocks. That works, but it adds syntax to text you have to read and edit for the rest of its life.
This plugin uses something already in your notes: the bullet you happened to type. Change one character and the section's default state changes with it.
How it works
Obsidian's parser discards the bullet character, because CommonMark defines the three markers as equivalent. So the plugin reads the raw Markdown instead, finds list items written with the configured characters, and applies CodeMirror fold ranges to them when the note opens.
Installation
From Obsidian
Open Settings → Community plugins → Browse, search for Fold by Bullet, then install and enable it.
Manually
- Download
main.jsandmanifest.jsonfrom the latest release. - Create a folder called
fold-by-bulletinside<your vault>/.obsidian/plugins/. - Copy the files into it.
- Reload Obsidian and enable the plugin under Settings → Community plugins.
With BRAT
Install BRAT and add this repository.
Settings
| Setting | Default | What it does |
|---|---|---|
Fold - lists |
on | Items written with - collapse when the note opens |
Fold * lists |
off | Same, for * |
Fold + lists |
off | Same, for + |
Fold - [ ] tasks |
on | Checkboxes written with - collapse when the note opens |
Fold * [ ] tasks |
off | Same, for * |
Fold + [ ] tasks |
off | Same, for + |
| Fold when a note is opened | on | Turn off to fold only via the command |
| Excluded folders | empty | One path per line. Notes inside are never folded automatically |
Turn on every bullet and the plugin becomes "fold all lists on open". Turn on none and nothing happens.
Tasks are configured separately from plain items, since a checkbox reads as a different kind of thing even when it shares a bullet. A common arrangement is to fold reference material written with - while leaving - [ ] open, so today's work stays in front of you:
- Reference ← starts folded
- RFC 5545
- [ ] Ship the release ← stays open
- [ ] Tag it
- [ ] Write the notes
The settings screen is translated into English, Japanese, Simplified Chinese and Spanish, following Obsidian's own language setting.
Commands
- Fold by bullet — apply the rules to the current note. Ignores the folder exclusion list, since you asked for it explicitly.
- Unfold everything in this note — expand all folds.
- Convert to
-list, Convert to*list, Convert to+list — rewrite every line the cursor or selection touches into a list item using that bullet.
None of them ship with a default hotkey. Bind the ones you want under Settings → Hotkeys.
About the convert commands
Since the bullet decides whether a section starts folded, changing it is an editing action you will want to repeat. These commands give it a key.
They accept whatever the line currently is — a heading, a quote, an ordered item, another bullet, or a plain paragraph — and leave it as a list item with the bullet you asked for. A task marker is content rather than structure, so it survives:
- [ ] Ship the release → + [ ] Ship the release
Thematic breaks (---) and anything inside a fenced code block are skipped, so running a command over a whole note will not corrupt it.
Blank lines depend on how much is selected. Sweeping a selection across a note leaves its blank lines alone, but a cursor sitting by itself on an empty line gets a bare marker — pressing Enter and reaching for the command before typing is the normal way to start an item.
Limitations
- Editing view only. Reading view renders its own DOM and does not expose fold state. Notes opened in Reading view are unaffected.
- Obsidian's saved folds win on conflict. Obsidian restores its own per-file fold state when a note opens. The plugin applies its folds shortly afterwards, which means a section you deliberately expanded last session collapses again. Turn off Fold when a note is opened and use the command if you would rather keep Obsidian's memory.
- Bullet changes need a reopen. Editing
-to+does not unfold the section on the spot. Reopen the note or run the command. - Uses a private API. Reaching CodeMirror through
editor.cmis not part of Obsidian's public plugin API and may break in a future release.
Development
npm install
npm run dev # watch build
npm run build # type-check and produce a minified main.js
To test against a real vault, symlink the repository into its plugin folder:
ln -s "$(pwd)" /path/to/vault/.obsidian/plugins/fold-by-bullet
The fold detection in src/fold.ts is a pure function over an array of lines, so it can be exercised without Obsidian running.