Tag Notes

A #tag is a bare string. It cannot carry a description, aliases or properties of its own, a misspelt one silently becomes a new tag, and renaming one is a search-and-replace across the vault. A note has none of those problems, but tagging with links to notes loses what #tags give you: #parent/child hierarchy, the Tags pane with its tree and counts, and suggestions as you type.

Tag Notes makes the note the tag, so your tag pages are the tags themselves. A note is tagged by linking tag notes from a list property, keywords by default; a tag note names its parents in broader. The plugin brings back the hierarchy, a tag tree with counts, "tagged X or anything under X" lists, an @ suggester, and a previewed conversion of your existing #tags. All of it is plain frontmatter links, so the data stays readable with no plugin installed, and renaming a tag note renames the tag everywhere.

More screenshots

Demo vault

The documentation is an interactive demo vault. Every feature has a note that explains what it does and why you would want it, with a button that prepares a supplied set of tag notes so you can try each command on them at once.

Start reading here — it is plain markdown, so it works on GitHub with nothing installed.

A copy of the vault ships with every release. You can access it via any of the following:

1. Running the Tag Notes: Open demo vault command.
2. Downloading tag-notes-demo-vault.zip from the Releases. It unzips into a single tag-notes-demo-vault-<version> folder.
3. Browsing its source in demo-vault/ in this repository.

What it does

• Tag notes and their hierarchy: a note's tags are the links in its keywords list, a tag note lists its parents in broader, several parents are allowed, and a cycle is reported and broken without editing any note. Every tag has a direct count and a count with descendants, each note counted once: see Tag index.
• Tag tree: a sidebar view like the core Tags pane, with both counts, a filter, sorting by name or count, the notes of a subtree, and rename, new child tag and reveal on a right-click: see Tag tree.
• Tag this note and the @ suggester: choose a tag note by name or alias, or create one, and the link lands in the tags property: see Tag this note.
• Convert tags: turn the #tags of the whole vault or one folder into tag notes, #a/b into b with broader: [[a]], after a preview of every note it will change. In a vault kept in git, each run can be one commit that Undo a bulk operation... reverts: see Convert tags and undo with git.
• Queries and Bases: a tag-notes code block lists the notes tagged with a tag, with or without its descendants, and Copy Bases filter for tag subtree exports a subtree as a core Bases filter: see Queries and Bases.

Every setting is listed by its data.json key in Settings.

See also

My other Obsidian resources

Last searched for similar plugins on 2026-11-01.

For plugin developers

This plugin publishes a read-only API, declared in api.d.ts, for plugins and scripts that want to know whether a file is a tag note, a note's tags, the notes tagged with a tag with or without its descendants, a tag's parents, children, ancestors and descendants, and its counts.

import { watchPluginApi } from '@mnaoumov/obsidian-lib/plugin/plugin-api';

import type { TagNotesApi } from './api.d.ts';

const apiRef = watchPluginApi<TagNotesApi>({
  apiVersionRange: '^1.0.0',
  app: this.app,
  component: this,
  pluginId: 'tag-notes'
});

// `value` is always current: `null` while this plugin is not loaded, and non-`null` on its own once it is.
const api = apiRef.value;
if (api) {
  console.log(api.getCounts(tag)); // { direct: 1, withDescendants: 3 }
}

The handle comes from the @mnaoumov/obsidian-lib plugin registry; Cross-plugin APIs covers watchPluginApi and the registry from the library's side. The contract version is 1.0.0, and it moves independently of the plugin's own version, so ask for a range.

If you would rather not depend on @mnaoumov/obsidian-lib for the handle, the registry is a documented wire protocol you can read directly — see Plugin API protocol.

Installation

The plugin is available in the official Community Plugins repository.

Beta versions

To install the latest beta release of this plugin (regardless if it is available in the official Community Plugins repository or not), follow these steps:

1. Ensure you have the BRAT plugin installed and enabled.
2. Click Install via BRAT.
3. An Obsidian pop-up window should appear. In the window, click the Add plugin button once and wait a few seconds for the plugin to install.

Debugging

By default, debug messages for this plugin (id: tag-notes) are hidden.

If you need to enable them refer to the documentation.

Changelog

All notable changes to this project will be documented in the CHANGELOG.

Contributing

Contributions are welcome — see CONTRIBUTING to get set up.

Support

Filing an issue (for AI agents and humans)

Open issues through the issue forms, not as blank issues.

To report a bug from inside Obsidian, run the Tag Notes: Report a bug command. It opens the bug form with the plugin version, the Obsidian version and your operating system already filled in.

Filing from the CLI or the API (gh issue create --body, or an AI agent filing for you) skips the form, and gh issue create --template cannot load an issue form. In that case, open the matching form in .github/ISSUE_TEMPLATE/, copy every field as a ### <label> heading in the form's order, and fill in each one. Always state the plugin version, the Obsidian version and your operating system.

License

© Michael Naumov