Tag Taxonomy — Controlled Vocabulary for Wiki Tags You are enforcing consistent tagging across the wiki by normalizing tags to a controlled vocabulary. Before You Start Read .env to get OBSIDIAN_VAULT_PATH Read $OBSIDIAN_VAULT_PATH/_meta/taxonomy.md — this is the canonical tag list Read index.md to understand the wiki's scope The Taxonomy File The canonical tag vocabulary lives at $OBSIDIAN_VAULT_PATH/_meta/taxonomy.md . It defines: Canonical tags — the tags that should be used Aliases — common alternatives that should be mapped to the canonical form Rules — max 5 tags per page, lowercase/hyphenated, prefer broad over narrow Migration guide — specific renames for known inconsistencies Always read this file before tagging. It's the source of truth. Reserved System Tags visibility/ is a reserved tag group with special rules. These tags are not domain or type tags and are managed separately from the taxonomy vocabulary: Tag Purpose visibility/public Explicitly public — shown in all modes (same as no tag) visibility/internal Team-only — excluded in filtered query/export mode visibility/pii Sensitive data — excluded in filtered query/export mode Rules for visibility/ tags: They do not count toward the 5-tag limit Only one visibility/ tag per page Omit entirely when content is clearly public — no tag needed Never add visibility/internal just because content is technical; use it only for genuinely team-restricted knowledge When running a tag audit, report visibility/ tag usage separately — do not flag them as unknown or non-canonical When normalizing tags, leave visibility/ tags untouched — they are not subject to alias mapping. Mode 1: Tag Audit When the user wants to see the current state of tags: Step 1: Scan all pages Glob: $VAULT_PATH/*/.md (excluding _archives/, .obsidian/, _meta/) Extract: tags field from YAML frontmatter Step 2: Build a tag frequency table For each tag found, count how many pages use it. Flag: Unknown tags — not in the taxonomy's canonical list Alias tags — using an alias instead of the canonical form (e.g., nextjs instead of react ) Over-tagged pages — pages with more than 5 tags Untagged pages — pages with no tags or empty tags field Step 3: Report

Tag Audit Report

Summary

Total unique tags: 47

Canonical tags used: 32

Non-canonical tags found: 15

Pages over tag limit (5): 3

Untagged pages: 2

|

| | nextjs | react | 4 | | next-js | react | 2 | | robotics | ml | 1 | | windows98 | retro | 3 |

|

|

| | entities/jane-doe.md | 8 | ai, ml, founder, ... | Mode 2: Tag Normalization When the user wants to fix the tags: Step 1: Run audit (above) Step 2: Apply fixes For each page with non-canonical tags: Read the page Replace alias tags with their canonical form from the taxonomy If page has > 5 tags, suggest which to drop (keep the most specific/relevant ones) Write the updated frontmatter Example:

Before

tags : [ nextjs , ai , ml - engineer , windows98 , creative - coding , game , 8 - bit , portfolio ]

After

tags : [ react , ai , ml , retro , generative - art ] Step 3: Handle unknowns For tags that aren't in the taxonomy and aren't aliases: If the tag is used on 2+ pages, suggest adding it to the taxonomy If the tag is used on 1 page, suggest replacing it with the closest canonical tag Ask the user before making changes to unknown tags Step 4: Update taxonomy If new canonical tags were agreed upon, append them to _meta/taxonomy.md in the correct section. Mode 3: Tagging a New Page When you're creating a wiki page and need to choose tags: Read _meta/taxonomy.md Select up to 5 tags that best describe the page: 1-2 domain tags (what subject area) 1 type tag (what kind of thing) 0-1 project tags (if project-specific) 0-1 additional descriptive tags Use only canonical tags — never aliases If no existing tag fits, check if it's worth adding to the taxonomy Mode 4: Adding a New Tag When the user wants to add a tag to the vocabulary: Check if an existing tag already covers the concept (suggest it if so) If genuinely new, determine which section it belongs in (Domain, Type, Project) Add it to _meta/taxonomy.md with: The canonical tag name What it's used for Any aliases to redirect After Any Tag Operation Append to log.md : - [TIMESTAMP] TAG_AUDIT tags_normalized=N unknown_tags=M pages_modified=P Or for normalization: - [TIMESTAMP] TAG_NORMALIZE tags_renamed=N pages_modified=M new_tags_added=P

tag-taxonomy

安装