Add Blog Category

Learn how to add custom categories to organize your blog posts in Plainform.

Goal

By the end of this recipe, you'll have added custom categories to your blog that readers can use to filter posts.

Prerequisites

• A working Plainform installation
• Basic understanding of JSON syntax

Steps

{
  "blogPage": {
    "categories": [
      {
        "title": "All",
        "id": 1
      },
      {
        "title": "Category 1",
        "queryParam": "category-1",
        "id": 2
      },
      {
        "title": "Category 2",
        "queryParam": "category-2",
        "id": 3
      },
      {
        "title": "Category 3",
        "queryParam": "category-3",
        "id": 4
      }
    ]
  }
}

{
  "blogPage": {
    "categories": [
      {
        "title": "All",
        "id": 1
      },
      {
        "title": "Tutorial",
        "queryParam": "tutorial",
        "id": 2
      },
      {
        "title": "Product Updates",
        "queryParam": "product-updates",
        "id": 3
      },
      {
        "title": "Engineering",
        "queryParam": "engineering",
        "id": 4
      },
      {
        "title": "Company",
        "queryParam": "company",
        "id": 5
      }
    ]
  }
}

Using Categories in Blog Posts

When creating a blog post, use the exact queryParam value in the frontmatter:

---
title: My Tutorial Post
publishedAt: 2024-01-15
summary: Learn how to do something awesome
author: john-doe
category: tutorial
img: https://your-bucket-name.s3.region.amazonaws.com/image.jpg
---

Your content here...

Learn how to add blog posts →

Category Naming Best Practices

Good category names:

• Tutorial
• Product Updates
• Engineering
• Company News
• Case Studies
• How-To Guides

Avoid:

• Too many categories (5-7 is ideal)
• Overlapping categories (e.g., "Tutorials" and "How-To Guides")
• Vague names (e.g., "Miscellaneous", "Other")

Verification

After adding categories:

1. Visit /blog to see the category filter buttons
2. Click each category to verify filtering works
3. Create a test post with a category to confirm it appears in the correct filter
4. Check that the "All" category shows all posts

Common Issues

Category Filter Not Working

Issue: Clicking a category doesn't filter posts

Solution:

• Verify the queryParam in locales/en.json matches the category in your blog post frontmatter exactly
• Check for typos, case mismatches, or spaces that should be hyphens
• Ensure the blog post has a valid category field

Category Not Appearing

Issue: New category doesn't show up on the blog page

Solution:

• Check JSON syntax is valid (no trailing commas, proper quotes)
• Verify you saved the locales/en.json file
• Restart the dev server if hot reload didn't pick up changes
• Clear browser cache

Posts Not Filtering Correctly

Issue: Posts appear in wrong categories

Solution:

• Ensure each blog post's category field matches a queryParam exactly
• Check for extra spaces or special characters; multi-word category values should use hyphens
• Verify the category exists in locales/en.json

Next Steps

• Add Blog Post - Create posts with categories
• Add Blog Author - Add author profiles
• Locales & Site Config - Learn about locale management