Bulk Tag Manager

Bulk Tag Manager is a comprehensive tag management utility for Obsidian. It provides a unified, professional dashboard to rename, merge, delete, clean, standardise, and organise both tags and front matter properties across your entire vault. This plugin absorbed the functionalities from Tag Wrangler, by pjeby.

---

Table of Contents

• Features
  • Dashboard Overview
  • Rename, Merge, and Delete
  • Bulk Standardisation and Settings
  • Metadata Utilities
  • Tools
  • Protected Tags
  • Tag Aliases
  • Context Menu Integration
• Installation
• Usage
• Commands
• Tips
• Acknowledgements

---

Warning

This plugin contains a History system that allows you to undo any operation. However, if you are about to perform a destructive bulk process, it is recommended that you backup your vault before running bulk operations.

---

$\color{red}{\text{Features}}$

$\color{blue}{\text{Dashboard Overview}}$

The plugin provides two interfaces:

• Quick Actions Modal -- Accessed from the ribbon icon (Tags). Provides single-tag operations: rename, delete, search, tag page creation, and random note.
• Settings Dashboard -- Accessed from Settings or the Command Palette. Contains the full suite of bulk operations, vault-wide statistics, and advanced tools.

$\color{orange}{\text{Tag Statistics}}$

At the top of the Settings Dashboard, expand the Overview section to see real-time analytics:

• Total Tags -- Count of unique tags in your vault.
• Total Files -- Number of notes in the current scope.
• Case Consistency -- Breakdown of lowercase, uppercase, and mixed-case tags with a consistency progress bar.
• Separator Consistency -- Breakdown of kebab-case, snake_case, mixed, and unseparated tags.
• Clean Tags and Front Matter -- Count of clean tags vs. tags with special characters, plus detection of notes with unnecessarily quoted properties.
• Tag Format Style -- Count of files using YAML list format vs. inline array format, with one-click conversion buttons.
• Wiki Link Format Style -- Same format breakdown for wiki link properties (aliases, cssclasses, etc.).
• Tag Nesting -- Count of flat vs. nested (hierarchical) tags, with links to files containing nested tags.
• Locations -- Breakdown of tags in frontmatter vs. tags in the document body, with links to files containing inline body tags.
• Length -- Detection of unusually long tags (over 25 characters).
• Case Duplicates -- Automatic detection of tags that differ only by case (e.g. #Project vs #project), with a one-click "Merge all to canonical" button.
• Empty Tags -- Detection of files with empty tag fields in frontmatter.

Clicking any statistic opens a detailed list of the relevant tags or files.

$\color{orange}{\text{Invalid Tag Detection}}$

If any files contain malformed YAML tag syntax (missing commas, unquoted colons, invalid formatting), an Invalid Tags warning block appears below the Overview. Clicking Fix Invalid opens a modal where you can review each issue and apply automatic or manual fixes.

---

$\color{blue}{\text{Rename, Merge, and Delete}}$

$\color{orange}{\text{Tag Renaming}}$

Rename any tag across all files, in both frontmatter and the document body.

1. Go to the Rename Tag section.
2. Enter the Find tag (or use the Search button to browse existing tags with usage counts).
3. Enter the Replace tag. If the target tag already exists, a warning is displayed indicating the rename will merge the tags.
4. Click Rename.

Child tags are automatically updated: renaming #project to #work will also rename #project/active to #work/active in both frontmatter and body.

$\color{orange}{\text{Batch Rename}}$

Rename multiple tags simultaneously using a dedicated table of old/new pairs.

1. Go to the Batch Rename section.
2. Add as many rows as needed.
3. Enter the Old Tag and New Tag for each row.
4. Click Apply.

This is ideal for quickly reorganising small groups of tags without running multiple single rename operations.

$\color{orange}{\text{Batch Rename from CSV}}$

Perform large-scale tag restructuring by uploading a data file.

1. Go to the Batch Rename from CSV section.
2. Click Choose CSV and select a file with two columns: old_tag and new_tag.
3. Review the Preview of the first few pairs to ensure correct loading.
4. Click Apply.

The CSV should not contain headers or the # symbol (though the plugin handles them if present).

$\color{orange}{\text{Tag Merging}}$

Consolidate multiple tags into a single canonical tag.

1. Go to the Merge Tags section.
2. Enter Source tags (comma-separated, e.g. #film, #movie), or use the Select button for a multi-select modal with checkboxes.
3. Enter a Target tag (e.g. #cinema).
4. Click Merge.

Duplicate tags in the same file are automatically deduplicated after merging. Child tags are propagated (e.g. #film/drama becomes #cinema/drama).

$\color{orange}{\text{Nest Tags}}$

Create hierarchical structures by moving existing tags under a new parent.

1. Go to the Nest Tags section.
2. Enter the Parent tag (e.g. #work).
3. Enter the Tags to nest (comma-separated, e.g. #meetings, #tasks).
4. Click Nest.

Each child tag will be renamed to include the parent prefix (e.g. #work/meetings and #work/tasks).

$\color{orange}{\text{Tag Deletion}}$

Remove tags from all files in the current scope.

1. Go to the Delete Tags section.
2. Enter tags to delete (comma-separated), or use the Select or Search buttons.
3. Click Delete.

Deleting a parent tag also removes its child tags (e.g. deleting #project also removes #project/active and #project/done). Tags are removed from both frontmatter arrays and inline body occurrences. Trailing whitespace artifacts are automatically cleaned up.

$\color{orange}{\text{Pattern-Based Renaming (Regex)}}$

Advanced tag restructuring using Regular Expressions.

1. Go to Pattern Rename (Regex).
2. Enter a Pattern (e.g. ^category-(.*)).
3. Enter a Replacement (e.g. new-category/$1).
4. Click Apply.

Regex complexity is limited to prevent catastrophic backtracking (ReDoS). Frontmatter content is excluded from pattern matching to prevent YAML corruption.

---

$\color{blue}{\text{Bulk Standardisation and Settings}}$

$\color{orange}{\text{Conversion Rules}}$

Configure how tags should be formatted vault-wide:

• Case Strategy -- Lowercase, Uppercase, or No Change.
• Separator Style -- Snake_case, Kebab-case, or Preserve.
• Remove Special Characters -- Strip everything except letters, numbers, hyphens, and underscores.
• Flatten Diacritics -- Convert accented characters to their plain equivalents (e.g. a to a).
• Apply to Nested Tags -- Whether to process child tags during conversion.

Click Convert All to apply these rules across all files in the current scope. A preview modal shows exactly which files and lines will be changed before you confirm.

$\color{orange}{\text{Bulk Case Conversion}}$

In the Case statistics box, two buttons allow you to convert all tags in your vault to uppercase or lowercase in a single operation, independent of the Case Strategy setting.

$\color{orange}{\text{Scope Filtering}}$

Limit all operations to specific parts of your vault.

1. Enable Scope Filter.
2. Use Include Folders to specify which folders to process.
3. Use Exclude Folders to protect specific folders (e.g. Templates, Archive).
4. Optionally set a File Pattern Filter (regex) applied to file paths for fine-grained control.

All statistics, conversions, and bulk operations respect the active scope filter.

---

$\color{blue}{\text{Metadata Utilities}}$

$\color{orange}{\text{Clean Front Matter Formatting}}$

Removes unnecessary quotes and trims whitespace from all frontmatter fields across the vault. This addresses Obsidian's tendency to add defensive quoting around property values.

$\color{orange}{\text{Standardise to Inline Array}}$

Converts both tag properties and wiki link properties (such as aliases and cssclasses) to the inline array format ([value1, value2]) across all files in the current scope.

$\color{orange}{\text{Standardise to YAML List}}$

Converts both tag properties and wiki link properties to the multiline YAML list format across all files:

tags:
  - tag1
  - tag2

$\color{orange}{\text{Tag Format Conversion}}$

In the Tag Format Style statistics box, you can convert tags specifically (without affecting wiki link properties) between YAML list and inline array formats.

$\color{orange}{\text{Wiki Link Format Conversion}}$

In the Wiki Link Format Style statistics box, you can convert wiki link properties specifically between YAML list and inline array formats.

---

$\color{blue}{\text{Tools}}$

$\color{orange}{\text{Hierarchy View}}$

Visualise your tags as a collapsible, searchable tree to understand your taxonomy. Includes:

• A search field to filter the tree in real time.
• A sort dropdown (alphabetical, by count, by depth).
• Expand All / Collapse All controls.
• Click counts to see usage per tag node.

$\color{orange}{\text{Orphan Detection}}$

Find tags used fewer times than a configurable threshold (default: 2 files). The orphan modal lists all matching tags with their usage counts and provides a Delete All Orphans button for bulk cleanup.

$\color{orange}{\text{Tag List}}$

Generate a markdown file (All Tags.md) in your vault root listing every tag and its usage count, sorted alphabetically.

$\color{orange}{\text{History and Undo}}$

Every destructive operation (rename, merge, delete, convert, pattern rename, format conversion, property cleaning) is recorded with full file snapshots.

• Click History to view a chronological log of all operations.
• Click Undo on any operation to revert every affected file to its exact state before the operation.
• History is stored externally in the plugin's data directory to keep data.json small.
• Configure Max History Size (default: 50 entries) and History Expiration (default: 7 days) in Settings.

---

$\color{blue}{\text{Protected Tags}}$

Define tags that should never be modified by any rename, merge, or delete operation.

1. Go to Settings > Bulk Tag Manager > Protected Tags.
2. Add a tag (e.g. #status/active).
3. Use a wildcard (*) for prefix matching (e.g. #status/* protects #status/active, #status/done, etc.).

Protected tags are silently skipped during all bulk operations.

---

$\color{blue}{\text{Tag Aliases}}$

Define automatic correction rules that trigger when you save a note.

1. Go to Settings > Bulk Tag Manager > Aliases.
2. Add an Alias (e.g. wip) and a Canonical tag (e.g. work-in-progress).
3. Whenever you save a note containing #wip, it is automatically corrected to #work-in-progress.

Aliases work in both frontmatter and the document body. Child tags are also corrected (e.g. #wip/urgent becomes #work-in-progress/urgent). A debounce timer prevents conflicts during rapid editing.

---

$\color{blue}{\text{Context Menu Integration}}$

Right-click any tag in the tag pane, editor, reading view, or metadata properties panel to access:

• Rename -- Opens the rename prompt for that tag.
• Delete -- Deletes the tag with confirmation.
• Open / Create Tag Page -- Opens an existing tag page or creates a new one with the tag as an alias.
• New Search -- Opens a global search scoped to the tag.
• Require in Search -- Adds the tag as a required filter to the current search query.
• Exclude from Search -- Excludes the tag from the current search query.
• Open Random Note -- Opens a random note tagged with the selected tag (requires the Smart Random Note plugin).

Tags can also be dragged and dropped in the tag pane to restructure the hierarchy (e.g. dragging active onto project renames it to project/active).

Holding Ctrl/Cmd + Click on any tag in the editor or reading view opens its tag page, or prompts to create one.

---

$\color{red}{\text{Installation}}$

1. Download the latest release from GitHub.
2. Extract main.js, manifest.json, and styles.css into <vault>/.obsidian/plugins/bulk-tag-manager/.
3. Reload Obsidian and enable the plugin.

---

$\color{red}{\text{Usage}}$

• Click the Tags icon in the left ribbon for quick single-tag actions (rename, delete, search, tag page, random note).
• Use Settings > Bulk Tag Manager for bulk operations, vault-wide cleanup, statistics, and advanced tools.
• Right-click any tag in the tag pane, editor, or reading view for contextual actions.
• Use the Command Palette for direct access to common operations.

---

$\color{red}{\text{Commands}}$

Command	Description
Open Bulk Tag Manager Settings	Opens the full settings dashboard
Convert all tags (with preview)	Runs bulk conversion based on current settings with a preview
Generate Tag List	Creates a markdown file listing all tags and their usage counts
Show Tag Hierarchy	Opens the tag hierarchy tree view
Find Orphaned Tags	Scans for tags below the usage threshold
Undo Last Tag Operation	Reverts the most recent operation

---

$\color{red}{\text{Tips}}$

• Use Preview: The bulk convert option shows a preview of every change before applying. Use it to verify before committing.
• Check History: Use the History modal after any operation to verify exactly which files were changed and to undo if needed.
• Scope Filters: Use Include/Exclude folders to test operations on a sandbox folder before running them vault-wide.
• Protected Tags: Add critical tags (e.g. #status/*) to the protected list before running bulk operations to prevent accidental modification.
• Case Duplicates: Run the case duplicate check periodically. Tags like #Project and #project are treated as separate tags by Obsidian and can cause inconsistencies.

---

$\color{red}{\text{Acknowledgements}}$

This plugin incorporates and extends the context menu and tag page functionality originally created by pjeby in the Tag Wrangler plugin.