building a dynamic category page in mediumish

Why Create a Category Page?

Most Jekyll themes, including Mediumish, do not include a dynamic category page out of the box. A category page allows you to display all posts related to a specific topic, which significantly improves content organization, SEO, and user navigation.

How Categories Work in Jekyll

In Jekyll, categories are assigned in the front matter of posts. These categories are then grouped automatically by the site generator and made available through the site.categories variable.

categories: [jekyll, tips]

This makes it easy to loop through and display posts based on categories dynamically using Liquid.

Step-by-Step: Creating a Dynamic Category Page

1. Create a Layout for Category Pages

Start by creating a new layout file that defines the structure of your category page:

touch _layouts/category.html

Then, inside _layouts/category.html, use the following structure:

<h2>Posts in Category: {{ page.category }}</h2>

{% assign posts = site.categories[page.category] %}
{% for post in posts %}
  <div class="post-card">
    <h3><a href="{{ post.url }}">{{ post.title }}</a></h3>
    <p>{{ post.excerpt | strip_html | truncate: 120 }}</p>
  </div>
{% endfor %}

2. Generate Category Pages Automatically

Since Jekyll doesn’t create pages dynamically, we’ll need a generator to build one static HTML file per category. Create a file called generate_categories.rb in the _plugins folder:

module Jekyll
  class CategoryPageGenerator < Generator
    safe true

    def generate(site)
      site.categories.each do |category, posts|
        site.pages << CategoryPage.new(site, site.source, category, posts)
      end
    end
  end

  class CategoryPage < Page
    def initialize(site, base, category, posts)
      @site = site
      @base = base
      @dir  = "category/#{category}"
      @name = "index.html"

      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'category.html')
      self.data['category'] = category
      self.data['title'] = "Posts in #{category}"
    end
  end
end

3. Configure Your _config.yml

Ensure the plugin folder is enabled (note: GitHub Pages does not support custom plugins by default):

plugins:
  - jekyll-paginate
  - jekyll-feed
  # local plugin (only works on local build)
  - ./_plugins/generate_categories.rb

For GitHub Pages deployment, manually create the category pages instead of using plugins.

4. Manually Create Static Category Pages (for GitHub Pages)

If you're using GitHub Pages (which doesn’t support plugins), create one markdown file per category:

touch category/jekyll.md

Then in each file:

---
layout: category
category: jekyll
permalink: /category/jekyll/
---

5. Add Links to Categories in Your Blog

Now that you have category pages, you can link to them from your posts or navigation:

{% for category in site.categories %}
  <a href="/category/{{ category[0] }}/">{{ category[0] }}</a>
{% endfor %}

6. Style Your Category Page

Customize category.html layout to match your Mediumish blog's design. Use post thumbnails, publish dates, and excerpts to make each listing visually consistent with other parts of your site.

Bonus: Add Category Sidebar Widget

In _includes/sidebar.html or similar, list out categories so users can jump directly to relevant topics:

<ul>
  {% for category in site.categories %}
    <li><a href="/category/{{ category[0] }}/">{{ category[0] }}</a></li>
  {% endfor %}
</ul>

Case Study: Organizing a Mediumish Blog by Category

A blog with 100+ posts on web development benefited from implementing a category page. By splitting content into jekyll, html, seo, and hosting sections, average session duration increased 30%, and bounce rate dropped by 22% over three months.

Conclusion

A dynamic category page is essential for improving content structure and discoverability on a Mediumish Jekyll blog. Whether you're using plugins or manually creating the pages, it's a practical upgrade that helps both users and search engines understand your content better.