notque/vexjoy-agent / skills/content/content
content
UnverifiedContent operations: editorial calendar, marketing, publishing, social media management.
references/taxonomy-guidelines.md
View on GitHub# Taxonomy Guidelines for Technical Blogs
Best practices for organizing categories and tags on a technical blog.
---
## Core Principles
### 1. Taxonomy Serves Navigation
The primary purpose of taxonomy is to help readers find related content. Every category and tag should answer: "What other posts would someone interested in this post want to read?"
### 2. Consistency Over Creativity
Consistent naming is more valuable than clever naming. Readers learn your taxonomy over time; changing or varying terms creates confusion.
### 3. Fewer Categories, More Tags
Categories = broad, stable, few (3-7)
Tags = specific, dynamic, many (10-30 active)
### 4. Lowercase with Hyphens
Standard format: `lowercase-with-hyphens`
Prefer:
- CamelCase: `HugoDebugging`
- Underscores: `hugo_debugging`
- Spaces: `hugo debugging`
- Mixed case: `Hugo-Debugging`
---
## Categories Best Practices
### Purpose
Categories represent the content pillars of your blog. They answer: "What type of content is this?"
### Guidelines
| Guideline | Recommendation |
|-----------|----------------|
| Total count | 3-7 categories |
| Per post | 1-2 categories (usually 1) |
| Stability | Rarely change after initial setup |
| Hierarchy | Keep flat (avoid sub-categories for small blogs) |
### Recommended Categories for Technical Blogs
| Category | Content Type |
|----------|--------------|
| `technical-notes` | Deep dives, explanations, debugging journeys |
| `tutorials` | Step-by-step guides, how-to content |
| `opinion` | Commentary, perspectives, industry thoughts |
| `tools` | Reviews, comparisons, recommendations |
| `meta` | Site updates, blogging about blogging |
### Category Red Flags
- **Too many categories**: More than 7 suggests over-categorization
- **Empty categories**: Defined but never used
- **Overlapping categories**: `tutorials` and `how-to-guides` are synonyms
- **Multi-category posts**: Posts with 3+ categories are unfocused
---
## Tags Best Practices
### Purpose
Tags provide cross-cutting classification. They answer: "What specific topics does this post cover?"
### Guidelines
| Guideline | Recommendation |
|-----------|----------------|
| Total active | 10-30 tags |
| Per post | 3-5 tags |
| Minimum usage | Each tag should apply to 2+ posts |
| Specificity | Specific enough to be useful, broad enough to be reusable |
### Tag Types
**Technology Tags**: The tools and platforms discussed
- `hugo`, `cloudflare`, `git`, `docker`, `nginx`
**Concept Tags**: The problems and activities covered
- `debugging`, `performance`, `deployment`, `security`, `configuration`
**Format Tags** (use sparingly): The content style
- `quick-tip`, `deep-dive`, `walkthrough`
### Tag Red Flags
- **Single-use tags**: Used only once (too specific)
- **Case variations**: `Hugo` and `hugo` as separate tags
- **Synonym duplicates**: `debugging` and `troubleshooting`
- **Title-as-tag**: Tag that mirrors the post title exactly
- **Over-tagging**: Posts with 7+ tags
---
## Naming Conventions
### Standard Format
All taxonomy terms should follow: `lowercase-with-hyphens`
### Transformation Rules
| Source | Becomes |
|--------|---------|
| Hugo | `hugo` |
| GitHub Actions | `github-actions` |
| CI/CD | `cicd` or `ci-cd` |
| S3 | `s3` |
| Node.js | `nodejs` |
| .NET | `dotnet` |
### Pluralization
Prefer singular forms:
- `template` not `templates`
- `tutorial` not `tutorials`
- `tool` not `tools`
Exception: When the plural is the common term:
- `kubernetes` (never `kubernete`)
- `analytics` (never `analytic`)
### Abbreviations
Use the most recognizable form:
- `k8s` OR `kubernetes` (pick one and be consistent)
- `cicd` OR `continuous-integration` (not both)
- `aws` not `amazon-web-services`
---
## Maintenance Cadence
### Monthly Review
- Check for new orphan tags
- Review tag counts (merge low-usage tags)
- Verify no case inconsistencies
### Quarterly Review
- Evaluate category structure
- Identify tag consolidation opportunities
- Update taxonomy documentation
### Per-Post Workflow
Before publishing:
1. Check if existing tags apply (reuse > create)
2. Verify tag naming matches conventions
3. Assign 1-2 categories maximum
4. Assign 3-5 tags
---
## SEO Considerations
### Tag Pages
Each tag generates a page listing all posts with that tag. For SEO value:
- Tags need 2+ posts to provide value
- Popular tags should have meaningful descriptions
- Tag slugs should be search-friendly terms
### Category Pages
Categories are major navigation entry points:
- Should have custom descriptions
- Consider adding featured posts
- Keep count balanced (avoid 1-post categories)
### Internal Linking
Taxonomy creates automatic internal linking:
- Related tags link related content
- Category pages consolidate topic clusters
- Cross-tag discovery helps readers explore
---
## Common Taxonomy Gaps
### 1. Over-Specific Tags
Bad: `hugo-template-debugging-with-console-log`
Good: `hugo`, `templates`, `debugging`
### 2. Under-Specific Tags
Bad: `programming`
Good: `go`, `python`, `javascript`
### 3. Redundant Tags
Bad: `hugo-themes`, `hugo-templates`, `hugo-shortcodes`, `hugo-config`
Good: `hugo` + `themes`, `hugo` + `templates`, etc.
### 4. Inconsistent Naming
Bad: `Cloudflare`, `cloudflare`, `CloudFlare`
Good: `cloudflare` (everywhere)
### 5. Category Creep
Bad: Adding new categories for each content type
Good: Mapping new content to existing categories
---
## References
- Hugo Taxonomies Documentation: https://gohugo.io/content-management/taxonomies/
- Google SEO Best Practices for Categories: https://developers.google.com/search/docs/specialty/ecommerce/best-practices
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 |