l-tagging

Tagging rules and conventions for MDX frontmatter tags and categories. Use PROACTIVELY when: (1) Writing or editing MDX frontmatter tags/categories, (2) Creating new articles, guide episodes, highligh...

Tagging Rules

Tag System Structure

Dual-key system: ASCII key (for URLs/frontmatter) + Japanese label (for display).

Article tags: lib/data/taxonomy-articles.ts (~104 tags)
Product tags: lib/data/taxonomy-products.ts (~103 tags)
Categories: lib/data/taxonomy.ts (10 categories)
Blacklist: lib/data/taxonomy.ts (TAG_BLACKLIST export)
Validation: lib/mdx/frontmatter.ts (validateFrontmatter())

Tag Blacklist

Blacklisted tags cause build failures. Check TAG_BLACKLIST in lib/data/taxonomy.ts before using tags.

Current blacklist:

Blacklisted tag	Use instead
`oxi-one-mkii`	`oxi-one`

Build error: tag "oxi-one-mkii" is blacklisted - use "oxi-one" instead

Core Rules

ASCII keys only in frontmatter, kebab-case (e.g., oxi-one, how-to-build)
No duplicate concepts — one tag per concept (e.g., power not power-supply)
Only use registered tags — check taxonomy-articles.ts or taxonomy-products.ts
Do not invent uncommon/niche tags — if a concept doesn’t have a registered tag, use the closest existing one or omit it. Only add new tags to taxonomy files when the concept is broadly useful across multiple articles
Categories determine structure; tags are for discovery — don’t conflate them

Content-Type Tagging Patterns

Guide articles (`contentType: guides`)

tags:
  - guide              # Always required
  - oxi                # Brand family (if applicable)
  - oxi-one            # Specific product line
  - sequencer          # Functional keyword
  - <topic-tags>       # Episode-specific (e.g., pattern, workflow, setup)
categories:
  - oxi-one-mkii-guide # Series slug — must match guide-series.mjs
  - guide              # Always required

Highlights / newsletters (`contentType: highlights`)

tags:
  - takazudo-modular-highlights  # Always required
  - newsletter                   # Always required
  - <product/topic tags>         # What's featured
categories:
  - news

Notes / columns (`contentType: notes`)

tags:
  - <relevant-topic-tags>
categories:
  - column    # For educational/opinion columns
  - news      # For announcements
  - guide     # If guide-like content

Build guides

tags:
  - guide
  - how-to-build       # Always for assembly guides
  - diy-kit
  - <product-tags>
categories:
  - guide

Valid Categories (exhaustive list)

news, oxi-one-guide, oxi-one-mkii-guide, oxi-meta-guide, oxi-e16-guide, addac215-guide, products-intro, wip, guide, column

Detailed Tag Reference

For the full tag lists and per-article assignments, read:

doc/src/content/docs/inbox/tags-article.md — article tag rules and assignments
doc/src/content/docs/inbox/tags-products.md — product tag rules and assignments
doc/src/content/docs/inbox/mdx-frontmatter-spec.md — frontmatter field specification