Tagging Folder
Dryden Bryson4 downloadsAutomatically tag notes based on the folder they live in.
- Overview
- Scorecard
- Updates3
🏷️ Tagging Folder
Tag notes automatically based on the folder they live in.
Features · Install · Usage · Settings · Limitations · Contributing
✨ Features
🏷️ Hands-off tagging
|
🔄 Stays in sync
|
Whenever tags would be removed, the plugin asks first. Tick Don't ask again to make your answer the default, and change it any time in settings.
📦 Installation
[!IMPORTANT] Requires Obsidian 1.13 or later.
Manual install
- Download
main.js,manifest.jsonandstyles.cssfrom the latest release, or build them yourself. - Copy them into
<Vault>/.obsidian/plugins/tagging-folder/. - Reload Obsidian and enable Tagging Folder in Settings → Community plugins.
Beta builds with BRAT
- Install BRAT.
- Select Add beta plugin and enter
Dryd33n/obsidian-tagging-folder.
🚀 Usage
- Right-click a folder and select Auto-tag….
- Enter a tag name, such as
projectorarea/work. A leading#is fine. - Choose whether to tag existing notes and include subfolders. Both are on by default.
- Select Enable.
From then on, notes created in or moved into the folder get the tag in their tags property.
[!TIP] Right-click the folder again to edit its tag, re-apply it to every note in the folder, or disable auto-tagging.
🔀 Moving notes
| You move a note… | What happens |
|---|---|
| Into an auto-tag folder | The folder's tag is added |
| Between two auto-tag folders | The new folder's tag is added and the old one is removed (or kept, see Settings) |
| Out to a normal folder | The tag is removed or kept, see Settings |
| Within the same auto-tag folder | Nothing changes |
Moving a folder of notes gives a single prompt for all of them. Closing a prompt without choosing always keeps the tags.
⚙️ Settings
Under Settings → Tagging Folder you'll find every auto-tag folder, each with an ⚙ Edit button and a Delete button that disables auto-tagging for that folder, and two behaviour settings. All of them show up in Obsidian's settings search.
| Setting | Options | Default |
|---|---|---|
| When disabling a folder's auto-tagging | Ask every time · Remove tags · Keep tags | Ask every time |
| When a note leaves an auto-tag folder | Ask every time · Remove tag · Keep tag | Ask every time |
Per folder:
| Option | Default |
|---|---|
| Tag name | — |
| Include subfolders | ✅ On |
| Tag existing notes (when enabling) | ✅ On |
[!NOTE] Turning Include subfolders off counts as the subfolder notes leaving the folder, so it follows the "leaves an auto-tag folder" setting.
⚠️ Limitations
- Tags you added by hand can be removed. If a note already had
#projectbefore its folder was auto-tagged, disabling the folder or moving the note out can remove it. - Changes made while Obsidian is closed aren't picked up. If notes are moved by sync or your file manager while Obsidian isn't running, use Re-apply tag to catch up.
- Only Markdown notes are tagged. Canvases, PDFs and other files are ignored.
- The vault root can't be auto-tagged.
- Templates that take longer than 10 seconds to fill in a new note (for example, an unanswered Templater prompt) can overwrite the tag.
[!NOTE] Privacy: everything runs locally. The plugin only edits the
tagsproperty of notes in your auto-tag folders.
🤝 Contributing
Issues and pull requests are welcome.
- 🐛 Bugs: open an issue with your Obsidian version, OS and the steps that reproduce the problem.
- 💡 Features: open an issue to discuss before starting large changes.
Development setup
git clone https://github.com/Dryd33n/obsidian-tagging-folder.git
cd obsidian-tagging-folder
npm install
npm run dev # rebuild main.js on change
Copy main.js, manifest.json and styles.css into a test vault at .obsidian/plugins/tagging-folder/, then reload Obsidian.
Testing
npm run lint # Obsidian's plugin lint rules
npm test # unit tests for the tagging logic
npm run test:e2e # end-to-end tests in a real Obsidian instance
The end-to-end suite builds a fresh test-vault/, launches an isolated Obsidian instance with its own data folder (your normal Obsidian and vaults are untouched), runs every flow through the real UI and checks the notes on disk. It uses the newest Obsidian version your install has downloaded; set OBSIDIAN_ASAR= (empty) to test the older version bundled with the installer instead.
| Variable | Effect |
|---|---|
OBSIDIAN_PATH |
Obsidian executable, if it isn't at %LOCALAPPDATA%\Obsidian\Obsidian.exe |
OBSIDIAN_ASAR |
Test a specific Obsidian app version (obsidian-x.y.z.asar) |
KEEP_OPEN=1 |
Leave the test instance running afterwards to explore the test vault |
E2E_DEBUG=1 |
Log the active window before each test and list open modals on failure |
Pull request checklist
- Branch from
masterand keep each PR focused on one change. -
npm run lint,npm run build,npm testandnpm run test:e2epass. - The PR describes what you tested in Obsidian.
- No
main.jsor other build output committed. - Any UI text uses sentence case.
Releasing
Bump version in manifest.json and package.json, add the version to versions.json, then push a tag with the same version (no v prefix). CI builds the plugin, attests the release files and creates a draft release for you to publish.
Code layout
| Path | Contents |
|---|---|
src/main.ts |
Plugin lifecycle, vault events and rule actions |
src/rules.ts |
Folder scope and tag logic (no Obsidian dependency) |
src/modals.ts |
Folder modal and confirmation prompts |
src/settings.ts |
Settings tab |
tests/ |
Unit and end-to-end tests |
PLAN.md |
Behaviour spec |