Add post series/collections via frontmatter

[x3ek]

Description

Add support for grouping related posts into an ordered series using frontmatter fields. This lets authors create multi-part tutorials, article series, or any ordered collection of posts.

Frontmatter

---
title: "Building a Blog Engine - Part 2"
date: 2026-02-15
series: "Building a Blog Engine"
series_order: 2
---

Fields

• series: str | None — Name of the series this post belongs to (case-sensitive match)
• series_order: int | None — Position within the series (1-based, lower = earlier)

Behavior

• Posts with the same series value are grouped together
• Ordered by series_order, then by date as tiebreaker
• Template context receives:
  • series_name — the series name
  • series_posts — ordered list of all posts in the series
  • series_prev — previous post in series (or None)
  • series_next — next post in series (or None)
  • series_index — 1-based position of current post in series
  • series_total — total number of posts in the series

Template Usage

Themes can render series navigation:

{% if series_name %}
<nav class="series-nav">
  <h3>Series: {{ series_name }} ({{ series_index }}/{{ series_total }})</h3>
  {% if series_prev %}<a href="/posts/{{ series_prev.slug }}">← Previous</a>{% endif %}
  {% if series_next %}<a href="/posts/{{ series_next.slug }}">Next →</a>{% endif %}
</nav>
{% endif %}

Implementation Notes

• Add series and series_order fields to FrontMatter model
• Add series context computation in routers/posts.py (post detail route)
• Use cached post list to find series siblings — no extra API calls needed
• Series navigation is only shown on post detail pages, not listings
• A future enhancement could add a /series index page or /series/{name} listing

Acceptance Criteria

• series and series_order fields added to FrontMatter
• Series context variables passed to post template
• Prev/next navigation works correctly at series boundaries
• Posts without series are unaffected
• Draft posts in a series are excluded for non-admin users

— Claude