This comprehensive guide explains how tags and categories work in our Jekyll workspace, their relationship to archive browsing, and best practices for creating and using taxonomy effectively.

📋 Overview

Our content management system uses a dual taxonomy approach:

  • Categories: Broad, hierarchical content organization (typically 1 per post)
  • Tags: Specific, descriptive keywords (multiple per post)

Both systems work together to create powerful content discovery through automated archive pages and enhanced navigation.

🏗️ System Architecture

Jekyll Archive Integration

The taxonomy system integrates with Jekyll’s archive plugin to automatically generate:

  • Category archive pages at /category/{category-name}/
  • Tag archive pages at /tag/{tag-name}/
  • Paginated listings for each taxonomy term

FrontMatter CMS Integration

Our FrontMatter CMS configuration provides:

  • Visual taxonomy management in VS Code
  • Predefined category and tag options
  • Automatic validation and suggestions
  • Data consistency across content

Data File Structure

Taxonomy definitions are stored in:

docs/_data/
├── categories.yml  # Category definitions with metadata
└── tags.yml        # Tag definitions with metadata

Each taxonomy entry includes:

  • name: Display name
  • description: Purpose explanation
  • color: Visual identification (hex code)
  • icon: Optional emoji or symbol

📚 Categories System

Purpose and Design

Categories represent broad content areas and follow these principles:

  1. Hierarchical: Organized from general to specific
  2. Exclusive: Each post typically belongs to one primary category
  3. Stable: Categories change infrequently
  4. Descriptive: Clear content area indication

Available Categories

Category Purpose Color Icon
tutorial Step-by-step learning guides #28A745 📚
getting-started Initial setup and configuration #17A2B8 🚀
development Software development topics #007BFF 💻
typescript TypeScript specific content #3178C6 🔷
jekyll Jekyll static site generator #CC0000 💎
testing Testing strategies and frameworks #FF6B6B 🧪
deployment Deployment and DevOps topics #6F42C1 🚀
configuration Setup and configuration guides #FFC107 ⚙️
best-practices Recommended approaches #28A745 ⭐
documentation Documentation and writing #6F42C1 📖
navigation Site navigation and UX #17A2B8 🧭
announcements News and updates #FFC107 📢
linux Linux and Unix topics #FCC624 🐧

Category Best Practices

Choosing Categories

  1. Single Category Rule: Most posts should have one primary category
  2. Content Alignment: Category should match the main topic
  3. User Perspective: Consider how readers will browse content
  4. Future Consistency: Use existing categories when possible

Adding New Categories

When creating new categories:

  1. Check Existing: Review current categories first
  2. Validate Need: Ensure 3+ posts will use this category
  3. Clear Purpose: Define specific content area
  4. Update Data File: Add to docs/_data/categories.yml 
# Example new category
machine-learning:
  name: 'Machine Learning'
  description: 'AI and ML development topics'
  color: '#FF6B35'
  icon: '🤖'

🏷️ Tags System

Purpose and Design

Tags represent specific topics and follow these principles:

  1. Descriptive: Specific technologies, concepts, or tools
  2. Multiple: Posts can have many relevant tags
  3. Flexible: Easy to add new tags as needed
  4. Searchable: Enable precise content discovery

Available Tags

Tag Description Color
typescript Microsoft’s typed JavaScript #3178C6
jekyll Static site generator #CC0000
development Software development #28A745
vscode Visual Studio Code #007ACC
wsl Windows Subsystem for Linux #FCC624
testing Testing frameworks #FF6B6B
playwright End-to-end testing #45BA4B
jest JavaScript testing #C21325
markdown Markup language #083FA1
documentation Technical writing #6F42C1
docs Documentation content #6F42C1
guide How-to content #28A745
navigation Site navigation #17A2B8
tutorial Step-by-step guides #28A745
cpus Central processing units #007BFF
gpus Graphics processing units #FF6B35

Tag Best Practices

Choosing Tags

  1. Specific Technologies: Include framework/tool names
  2. Core Concepts: Tag main topics discussed
  3. Target Audience: Consider search terms users might use
  4. Reasonable Quantity: 3-8 tags per post optimal

Tag Naming Conventions

  • Lowercase: Use lowercase for consistency
  • Hyphens: Separate words with hyphens (machine-learning)
  • No Spaces: Avoid spaces in tag names
  • Descriptive: Choose clear, searchable terms

Adding New Tags

Process for new tags:

  1. Search Existing: Check current tags first
  2. Validate Uniqueness: Ensure no duplicates or near-duplicates
  3. Update Data File: Add to docs/_data/tags.yml
  4. Consider Aliases: Think about alternative names
# Example new tag
react:
  name: "React"
  description: "React JavaScript library for building user interfaces"
  color: "#61DAFB"

🔄 Content Creation Workflow

Using FrontMatter CMS

  1. Open VS Code: Launch VS Code with FrontMatter extension
  2. Access CMS: Use Command Palette (Ctrl+Shift+P) → “FrontMatter: Open Dashboard”
  3. Create Content: Choose content type (post, documentation, page)
  4. Select Taxonomy: Use dropdown menus for categories and tags
  5. Validate: FrontMatter validates against data files

Manual Front Matter

---
layout: post
title: "Your Post Title"
description: "Brief description for SEO"
date: 2025-08-05
categories:
  - development  # Single primary category
tags:
  - typescript   # Multiple specific tags
  - testing
  - vscode
author: "Your Name"
---

Validation Checklist

Before publishing:

  • Category exists in docs/_data/categories.yml
  • All tags exist in docs/_data/tags.yml
  • Category aligns with main content topic
  • Tags are specific and relevant
  • Spelling and formatting are correct

📊 Archive Browsing

Generated Archive Pages

Jekyll automatically creates:

Category Archives:

  • URL pattern: /category/{category-name}/
  • Lists all posts in that category
  • Paginated if many posts
  • Includes category metadata

Tag Archives:

  • URL pattern: /tag/{tag-name}/
  • Lists all posts with that tag
  • Cross-references related tags
  • Shows tag description

Archives integrate with site navigation:

  1. Category Menu: Main navigation by content area
  2. Tag Cloud: Popular tags visualization
  3. Related Content: Posts with similar tags
  4. Breadcrumbs: Category-based navigation paths

User Experience

The taxonomy system enhances UX through:

  • Discovery: Browse content by interest area
  • Filtering: Narrow results by specific topics
  • Related Content: Find similar articles
  • Progressive Disclosure: From general (category) to specific (tags)

🛠️ Maintenance and Management

Regular Maintenance Tasks

Monthly Review

  1. Usage Analysis: Check which tags/categories are unused
  2. Consistency Check: Verify naming conventions
  3. Data Validation: Ensure all used terms have data file entries
  4. Archive Testing: Verify archive page generation

Quarterly Cleanup

  1. Taxonomy Audit: Review all categories and tags
  2. Consolidation: Merge similar or redundant terms
  3. Performance Check: Ensure fast archive page loading
  4. SEO Review: Optimize for search engines

Data File Management

Categories Data File

Location: docs/_data/categories.yml

category-name:
  name: 'Display Name'
  description: 'Purpose and scope description'
  color: '#HexColor'
  icon: '📚'  # Optional emoji

Tags Data File

Location: docs/_data/tags.yml

tag-name:
  name: "Display Name"
  description: "What this tag represents"
  color: "#HexColor"

Adding New Taxonomy Terms

Step-by-Step Process

  1. Research: Check existing terms for alternatives
  2. Plan: Define purpose and scope clearly
  3. Add Data: Update appropriate YAML file
  4. Test: Create test content using new term
  5. Validate: Check archive page generation
  6. Document: Update this guide if needed

Validation Commands

# Test Jekyll build with new taxonomy
cd docs
bundle exec jekyll build --drafts

# Check for missing data file entries
npm run taxonomy:validate  # If available

🔍 Troubleshooting

Common Issues

FrontMatter Not Showing Taxonomy

Symptoms: Categories/tags don’t appear in Data tab

Solutions:

  1. Check frontmatter.json taxonomy configuration
  2. Verify data files exist and are properly formatted
  3. Restart VS Code and FrontMatter extension
  4. Validate YAML syntax in data files

Archive Pages Not Generating

Symptoms: 404 errors on /category/ or /tag/ URLs

Solutions:

  1. Verify jekyll-archives plugin is enabled
  2. Check _config.yml archive settings
  3. Ensure taxonomy terms exist in data files
  4. Rebuild Jekyll site completely

Inconsistent Taxonomy Usage

Symptoms: Similar tags/categories with different names

Solutions:

  1. Run taxonomy audit script
  2. Standardize naming conventions
  3. Update content to use consistent terms
  4. Create alias system if needed

Validation Scripts

Check Taxonomy Consistency

# Find posts without categories
grep -L "categories:" docs/_posts/*.md

# Find posts without tags
grep -L "tags:" docs/_posts/*.md

# List all used taxonomy terms
grep -h "categories:\|tags:" docs/_posts/*.md | sort | uniq

📈 Advanced Features

Custom Archive Layouts

Create specialized archive templates:

docs/_layouts/
├── archive.html        # Default archive layout
├── category-archive.html  # Category-specific layout
└── tag-archive.html    # Tag-specific layout

Taxonomy-Based Navigation

Generate dynamic navigation:

<!-- Category navigation -->
{% for category in site.data.categories %}
  <a href="/category/{{ category[0] }}/" style="color: {{ category[1].color }}">
    {{ category[1].icon }} {{ category[1].name }}
  </a>
{% endfor %}

Related Content System

Use tags for content recommendations:

<!-- Related posts by shared tags -->
{% assign related_posts = site.posts | where_exp: "post", "post.tags contains page.tags[0]" | limit: 3 %}

🎯 Best Practices Summary

Content Creators

  1. Plan Taxonomy: Choose categories and tags before writing
  2. Be Consistent: Use established terms when possible
  3. Think User-First: Consider how readers will discover content
  4. Validate Early: Check taxonomy exists in data files

Site Maintainers

  1. Regular Audits: Review taxonomy usage monthly
  2. Performance Monitoring: Track archive page load times
  3. User Analytics: Monitor which archives are popular
  4. Documentation: Keep this guide updated

Development Team

  1. Automation: Create scripts for taxonomy validation
  2. Testing: Include taxonomy in CI/CD pipeline
  3. Monitoring: Track archive page generation errors
  4. Performance: Optimize archive page queries

📚 Resources

Configuration Files

  • frontmatter.json: FrontMatter CMS configuration
  • docs/_config.yml: Jekyll site configuration
  • docs/_data/categories.yml: Category definitions
  • docs/_data/tags.yml: Tag definitions

Archive Examples

External Documentation

Last Updated: August 5, 2025
Maintainer: MIJUG Development Team
Related Documentation: Content Management Guide