# tag-wrangler renames Obsidian tags and turns them into pages

> tag-wrangler is an Obsidian plugin that adds a context menu to tags in the tags pane and in note bodies, so tags can be renamed across the vault, turned into notes with an alias, folded into searches, or dragged between panes. Its own warning is blunt: renaming a tag can be irreversible, so back up the vault first.

**pjeby/tag-wrangler** — Rename, merge, toggle, and search tags from the Obsidian tag pane

- Repository: https://github.com/pjeby/tag-wrangler
- Stars: 932 · Forks: 38
- Language: JavaScript
- License: ISC
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/pjeby-tag-wrangler

## A context menu on the tags pane, and nothing else

Obsidian ships a tags view that lists the tags in a vault, and clicking a tag runs a global search for it. That is enough for reading a vault, and not enough for maintaining one. tag-wrangler adds a right-click menu to those tags so the maintenance operations live next to the tags themselves.

The menu entries are the feature list in concrete form. You can open or create a tag page, rename a tag together with all of its subtags, start a new search for the tag, add the tag as a requirement to the current search, add an exclusion for the tag, open a random note carrying that tag, and collapse or expand all tags at the same level in the tree. Version 0.6.0 extended the set by adding the context menu to tags in the body of a note in both editing and reading view, along with drag and drop for renaming and reorganising tags and for dragging a tag into an editor pane as plain text.

Which entries appear depends on context. The README says some actions may not be available depending on the current state of the search and tag views, and gives the example that expand and collapse are only offered when the tags view is showing tags in a hierarchy.

One entry has an external dependency. Opening a random note with that tag only works if the Smart Random Note plugin is installed and enabled, so tag-wrangler is not entirely self-contained.

## Renaming a tag rewrites its subtags too, and that is the risky part

The rename action is the one that matters for a vault that has grown, and the one the plugin is careful about. Renaming a tag also renames all of its subtags, so a rename from #project to #work has to rewrite #project/alpha and #project/beta as well as #project.

The README calls this potentially an irreversible operation and suggests backing up your data before beginning a rename. That warning is not boilerplate. The rename has to reach into note bodies and metadata across the whole vault, and there is no documented undo in what the README describes.

The mechanism behind it is partly explained by the tag page work. When a tag has an associated tag page, renaming the tag automatically updates the alias on that page, so the page keeps pointing at the right tag. That part is automatic and reliable. The bulk rewrite of tag references in note bodies is the part the plugin warns you about.

The other tag page feature worth knowing here is that the plugin does not support automatic conversion of tag references to page links or the reverse, though it says this may come in a future version. In the meantime you can use Obsidian's backlinks to find and change such references from the tag page. Viewing a tag page's unlinked mentions shows every location where the tag was used in a note body, and the link buttons there convert them into page links. Converting page links back into tags requires hand editing.

## A tag page is a note whose alias is a tag

The idea behind a tag page is to get the visibility of a tag and the content and outbound linking of a note in one object. Right-click a tag in the tags view and choose Create Tag Page, and Obsidian creates a new note carrying an alias equal to the selected tag. From then on the tag and the note are the same thing: the tag opens the page, and the page documents the tag.

The note can be renamed or moved anywhere in the vault as long as it keeps the alias, and renaming the associated tag updates that alias automatically.

Any note can serve as a tag page, not just the ones the plugin creates, and the README notes that even a Kanban board or an Excalidraw drawing can be one. The condition is that the note has a tag as a valid Obsidian alias. There are two ways to check whether that is true. Type # followed by the tag name into the quick switcher and see whether the page appears with the tag as an alias, or switch the note to preview and look at the Aliases entry in the metadata box at the top, which shows a shape with an arrow and a # in front when the alias is recognised.

## Alt-click opens the page without losing your place in the tags tree

Creating a page from the menu and opening one are different gestures, and the plugin offers both. Alt-clicking a tag, Option-clicking on Mac, in the tags view or in any note, in editing or reading view, opens the tag page, and offers to create one if none exists. If you cancel that prompt, the normal click behaviour of globally searching for the tag applies.

Holding Ctrl/Cmd while doing the same thing opens the tag page in a new pane instead, as does a middle click plus Alt or Option.

There is a keyboard route as well. Typing the tag name into the quick switcher, whose default hotkey is Ctrl/Cmd-O, opens the page, so you can reach a tag page without touching the mouse.

Hover previews work too. Hovering a tag in the tags view or in a markdown view pops up a preview of the tag page. The plugin is careful not to override your habits here: it respects your existing settings for hovering links in editor and preview views, and adds a separate setting for the tags view that decides whether the Ctrl or Cmd key must be held while hovering a tag there.

## Alias syntax has to be quoted, and Obsidian only reads the first alias field

This is where tag pages fail for most people, and the README is specific about it. Obsidian recognises the first field named Alias or Aliases, matched case insensitively, and expects either a YAML list of strings or a single string of aliases separated by commas. To be recognised as a tag alias, the string has to be quoted, and a tag alias must not contain whitespace or any other text.

These are the forms the README gives as valid, each of which makes the note the tag page for #some/tag.

```yaml
---
Alias: "#some/tag"
---
Aliases: [ "#some/tag", "another alias" ]
---
alias:
  - some alias
  - "#some/tag"
  - another alias
---
aliases: "some alias, #some/tag, another alias"
---
```

Two failure modes follow from the rules. Unquoted tags in a list are not recognised, which produces a page that silently is not a tag page. And if a note has two alias fields, only the first is read, so a second one is ignored rather than merged.

One more edge case is documented. Nothing prevents the same alias from being added to more than one note, and in that case the plugin selects the tag page at random from the available options. If two notes claim the same tag, which one opens is not deterministic.

## Search operators and drag and drop for reorganising the hierarchy

The plugin also treats tags as search operators rather than only as labels. Two menu entries work on the current search: one adds the tag as a requirement, written in the README as tag:#whatever, and the other adds an exclusion, written as -tag:#whatever. A third entry starts a new search for the tag, which the README describes as similar to a plain click.

The drag and drop features added in 0.6.0 cover two different jobs. Dragging a tag onto another tag renames or reorganises it, so the hierarchy can be restructured by moving rather than by typing a new name at every level. Dragging a tag from the tags view or from a note preview into an editor pane inserts it as text at the cursor, which is the quickest way to reference a tag you already use often without typing it.

Together these make the tags pane an editing surface rather than a read-only index. The context menu in the note body means the same operations are available on the tags you actually wrote in prose, which is where drift usually starts.

## Maintenance, licence and how the plugin is built

The plugin is released under the ISC licence, with the licence text in the LICENSE file, so it can be used and modified in personal or commercial vaults. The last push to the repository was on 2026-08-13, and the release history shows version 0.6.5 published on that date, with 0.6.4 and 0.6.3 both published on 2025-03-11. The gap between 0.6.4 and 0.6.5 is long compared with the gap between 0.6.3 and 0.6.4, so treat the version number as moving in bursts rather than on a schedule.

The build setup is visible in the repository. The package.json declares pnpm as its package manager at version 7.33.6, and the development dependencies include the Obsidian API at version 1.3.5, the yaml package, monkey-around and uneventful for its event handling, and the ophidian build tooling.

```json
  "scripts": {
    "dev": "node ophidian.config.mjs dev",
    "build": "node ophidian.config.mjs production"
  },
```

So a fork is built by running the dev or build script through ophidian.config.mjs, which is also the file that drives the plugin's development workflow. The top level of the repository holds src/, manifest.json, versions.json and jsconfig.json, and the plugin is installed the same way any community plugin is: search for tag wrangler in the Community Plugins interface, or use the link the README provides to open it in your most recently used vault, then select Install and Enable.

## Conclusion

tag-wrangler fits an Obsidian user with a large tag hierarchy and a habit of letting tags drift, because renaming a tag with its subtags in one action is the operation Obsidian itself does not offer. It is the wrong tool if your vault stays small enough that tags never diverge, and it cannot convert between tags and page links for you. Verify first that the Tags View core plugin is enabled, since the plugin contributes only a context menu and has no interface of its own, and copy your vault before the first rename because the plugin describes that operation as potentially irreversible.

## FAQ

### How do I install tag-wrangler in Obsidian?

Search for "tag wrangler" in Obsidian's Community Plugins interface, or use the link in the README to open it in your most recently used vault, then select Install and Enable. You also need to enable the "Tags View" core plugin, because Tag Wrangler adds a context menu to that pane and has no interface of its own.

### Is renaming a tag in tag-wrangler reversible?

The README calls it potentially an irreversible operation and suggests backing up your data before starting a rename. The rename also applies to all subtags of the renamed tag, so the set of affected text is larger than it may first appear.

### What makes a note a tag page in tag-wrangler?

The note has to carry the tag as a valid Obsidian alias. Obsidian reads the first field named Alias or Aliases, expects a YAML list of strings or a comma separated string, and requires the tag to be quoted. Any page can serve, including a Kanban board or an Excalidraw drawing.

### Does tag-wrangler convert tags into page links automatically?

No. The README says it does not yet support automatic conversion of tag references to page links or the reverse, though it may in a future version. In the meantime you can use a tag page's unlinked mentions and the link buttons there to convert body references into page links, while converting page links back to tags needs hand editing.

### How do I add a tag to the current search in tag-wrangler?

Use the context menu entries that add the tag as a requirement, written tag:#whatever, or as an exclusion, written -tag:#whatever. A separate entry starts a new search for the tag, similar to a plain click on it.

## Sources

- [Issues](https://github.com/pjeby/tag-wrangler/issues)
- [License: ISC](https://github.com/pjeby/tag-wrangler/blob/master/LICENSE)
- [pjeby/tag-wrangler on GitHub](https://github.com/pjeby/tag-wrangler)
- [README](https://github.com/pjeby/tag-wrangler/blob/master/README.md)
- [Releases](https://github.com/pjeby/tag-wrangler/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pjeby-tag-wrangler