notque/vexjoy-agent / skills/content/content
content
UnverifiedContent operations: editorial calendar, marketing, publishing, social media management.
references/taxonomy-examples.md
View on GitHub# Taxonomy Examples: Good vs Bad
Real-world examples illustrating taxonomy best practices and failure modes.
---
## Category Examples
### Good: Focused Categories
```yaml
# Post 1: Debugging journey
categories:
- technical-notes
# Post 2: Step-by-step guide
categories:
- tutorials
# Post 3: Tool comparison
categories:
- tools
```
**Why good:**
- Each post has one clear category
- Categories are distinct and non-overlapping
- Easy for readers to navigate
### Bad: Overlapping Categories
```yaml
# Post 1: Over-categorized
categories:
- technical-notes
- tutorials
- how-to
- guides
# Result: Post appears in 4 different category pages
# Reader confusion: "Is this a tutorial or technical notes?"
```
**Why bad:**
- `tutorials`, `how-to`, `guides` are synonyms
- Post appears in multiple places, diluting each category
- Forces reader to check multiple categories
### Bad: Category Explosion
```yaml
# Site with 15+ categories after 20 posts:
categories: [
debugging, hugo, cloudflare, git, deployment,
tutorials, quick-tips, deep-dives, opinions,
tools, comparisons, security, performance,
frontend, backend, devops
]
# Each category has 1-2 posts
```
**Why bad:**
- Too granular - categories should be broad
- Most categories are topics, not content types
- Navigation becomes overwhelming
---
## Tag Examples
### Good: Balanced Tags
```yaml
---
title: "Debugging Hugo Template Rendering"
categories:
- technical-notes
tags:
- hugo
- templates
- debugging
- static-sites
---
```
**Why good:**
- 4 tags, each broadly applicable
- Mix of technology (`hugo`), concept (`debugging`), and topic (`templates`)
- Each tag likely used in other posts
### Good: Consistent Naming
```yaml
# Post 1
tags:
- cloudflare
- deployment
- cicd
# Post 2
tags:
- cloudflare
- dns
- configuration
# Post 3
tags:
- cloudflare
- performance
- caching
```
**Why good:**
- Consistent casing (`cloudflare` always lowercase)
- Tags are reusable across posts
- Creates meaningful "cloudflare" tag page with 3+ posts
### Bad: Inconsistent Naming
```yaml
# Post 1
tags:
- CloudFlare
- DEPLOYMENT
# Post 2
tags:
- cloudflare
- deploy
# Post 3
tags:
- Cloud-Flare
- Deploying
```
**Why bad:**
- `CloudFlare`, `cloudflare`, `Cloud-Flare` are treated as 3 different tags
- `DEPLOYMENT`, `deploy`, `Deploying` fragment the content
- Each tag page shows only 1 post instead of 3
### Bad: Over-Specific Tags
```yaml
---
title: "Fixing Hugo Template Context in Range Loops"
tags:
- hugo-template-context-issue-in-range-loops
- debugging-hugo-templates
- hugo-range-loop-fix
- solving-template-context-problems
---
```
**Why bad:**
- Tags mirror the title - no reuse value
- Each tag will only ever have 1 post
- Better approach: `hugo`, `templates`, `debugging`
### Bad: Over-Tagging
```yaml
---
title: "Quick Hugo Deployment Guide"
tags:
- hugo
- deployment
- static-sites
- jamstack
- netlify
- cloudflare
- github-actions
- cicd
- devops
- automation
- web-development
- frontend
- build-tools
---
```
**Why bad:**
- 13 tags is excessive
- Many are redundant (`jamstack`, `static-sites`, `frontend`)
- Dilutes each tag's signal
- Better: Pick 3-5 most specific tags
### Bad: Under-Tagging
```yaml
---
title: "Complete Guide to Hugo Theme Customization"
tags:
- hugo
---
```
**Why bad:**
- Only 1 tag provides minimal classification
- Misses obvious tags: `themes`, `customization`, `css`
- Reduces discoverability
---
## Taxonomy Audit Examples
### Healthy Taxonomy Output
```
===============================================================
TAXONOMY AUDIT: YourBlog
===============================================================
CATEGORIES (4 total):
technical-notes: 8 posts ||||||||..
tutorials: 5 posts |||||.....
opinion: 2 posts ||........
tools: 1 post |.........
TAGS (18 total):
hugo: 12 posts ||||||||||||
debugging: 6 posts ||||||....
deployment: 5 posts |||||.....
cloudflare: 4 posts ||||......
git: 4 posts ||||......
templates: 3 posts |||.......
performance: 3 posts |||.......
configuration: 2 posts ||........
[... 10 more tags ...]
HEALTH METRICS:
Total posts: 16
Posts with categories: 16/16 (100%)
Posts with tags: 16/16 (100%)
Avg tags per post: 3.8
Avg categories/post: 1.0
ISSUES FOUND: None
===============================================================
STATUS: Healthy taxonomy - no action needed
===============================================================
```
### Problematic Taxonomy Output
```
===============================================================
TAXONOMY AUDIT: YourBlog
===============================================================
CATEGORIES (9 total):
technical-notes: 3 posts |||.......
tutorials: 2 posts ||........
how-to: 2 posts ||........ ! overlaps with tutorials
guides: 1 post |......... ! overlaps with tutorials
opinion: 1 post |.........
tools: 1 post |.........
reviews: 0 posts .......... ! empty
meta: 0 posts .......... ! empty
misc: 1 post |......... ! vague
TAGS (42 total):
hugo: 6 posts ||||||....
Hugo: 2 posts ||........ ! case variation
HUGO: 1 post |......... ! case variation
debugging: 4 posts ||||......
debug: 2 posts ||........ ! synonym
troubleshooting: 1 post |......... ! synonym
cloudflare: 3 posts |||.......
CloudFlare: 1 post |......... ! case variation
git-submodules: 1 post |......... ! orphan
toml-config: 1 post |......... ! orphan
first-post: 1 post |......... ! orphan, non-reusable
[... 31 more tags ...]
HEALTH METRICS:
Total posts: 11
Posts with categories: 11/11 (100%)
Posts with tags: 11/11 (100%)
Avg tags per post: 5.8 ! too high
Avg categories/post: 1.3
Orphan tag ratio: 38% ! too high
ISSUES FOUND:
ORPHAN TAGS (used once - consider removing or merging):
! "git-submodules" -> merge into "git"?
! "toml-config" -> merge into "configuration"?
! "first-post" -> remove (not reusable)?
SIMILAR TAGS (consider consolidating):
! "Hugo" and "hugo" and "HUGO" -> standardize to "hugo"
! "CloudFlare" and "cloudflare" -> standardize to "cloudflare"
! "debug" and "debugging" and "troubleshooting" -> standardize to "debugging"
OVERLAPPING CATEGORIES:
! "tutorials", "how-to", "guides" -> consolidate to "tutorials"
EMPTY CATEGORIES:
! "reviews" - defined but unused
! "meta" - defined but unused
===============================================================
RECOMMENDATIONS:
1. Standardize "Hugo/hugo/HUGO" -> "hugo" (9 posts affected)
2. Merge "how-to" and "guides" into "tutorials" (3 posts affected)
3. Standardize "debug/debugging/troubleshooting" -> "debugging" (7 posts)
4. Remove empty categories "reviews", "meta"
5. Merge orphan tags or remove non-reusable ones
===============================================================
```
---
## Before/After Examples
### Example 1: Case Standardization
**Before:**
```yaml
# post-1.md
tags: ["Hugo", "deployment"]
# post-2.md
tags: ["hugo", "configuration"]
# post-3.md
tags: ["HUGO", "themes"]
```
**After:**
```yaml
# post-1.md
tags: ["hugo", "deployment"]
# post-2.md
tags: ["hugo", "configuration"]
# post-3.md
tags: ["hugo", "themes"]
```
**Result:** "hugo" tag page now shows all 3 posts instead of 3 separate pages.
### Example 2: Orphan Tag Merge
**Before:**
```yaml
# post-about-submodules.md
tags: ["git-submodules", "version-control"]
```
**After:**
```yaml
# post-about-submodules.md
tags: ["git", "version-control"]
```
**Result:** Post now appears on the well-populated "git" tag page.
### Example 3: Category Consolidation
**Before:**
```yaml
# tutorial-post-1.md
categories: ["tutorials"]
# tutorial-post-2.md
categories: ["how-to"]
# tutorial-post-3.md
categories: ["guides"]
```
**After:**
```yaml
# tutorial-post-1.md
categories: ["tutorials"]
# tutorial-post-2.md
categories: ["tutorials"]
# tutorial-post-3.md
categories: ["tutorials"]
```
**Result:** "tutorials" category now shows all 3 posts, easier navigation.
### Example 4: Adding Missing Tags
**Before:**
```yaml
# theme-post-1.md
title: "Customizing Hugo Themes"
tags: ["hugo", "css"]
# theme-post-2.md
title: "Creating a Hugo Theme from Scratch"
tags: ["hugo", "development"]
# theme-post-3.md
title: "Hugo Theme Performance Tips"
tags: ["hugo", "performance"]
```
**After:**
```yaml
# theme-post-1.md
title: "Customizing Hugo Themes"
tags: ["hugo", "css", "themes"]
# theme-post-2.md
title: "Creating a Hugo Theme from Scratch"
tags: ["hugo", "development", "themes"]
# theme-post-3.md
title: "Hugo Theme Performance Tips"
tags: ["hugo", "performance", "themes"]
```
**Result:** New "themes" tag page with all 3 related posts.
---
## YourBlog Recommended Taxonomy
### Categories
```yaml
# Only use these 4-5 categories:
categories:
- technical-notes # Deep dives, debugging, how-it-works
- tutorials # Step-by-step guides
- opinion # Perspectives, commentary
- tools # Reviews, recommendations
```
### Core Tags
```yaml
# Technology tags (the tools):
- hugo
- cloudflare
- git
- github-actions
- docker
- nginx
# Concept tags (the activities):
- debugging
- deployment
- performance
- configuration
- security
# Topic tags (the subjects):
- templates
- themes
- static-sites
- dns
- caching
```
### Tag Limits
- Per post: 3-5 tags
- Create new tag only if expected to use in 2+ posts
- Review orphan tags quarterly
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |