Template API reference

This page documents the stable contract for custom templates in BlogMore. All items listed here will remain compatible across all v2.x releases unless explicitly noted otherwise.

For a broader introduction to theming — including CSS variable overrides and example themes — see Theming.

Template context variables

Every template receives a context dictionary when it is rendered. The table below lists all variables that are available in every template.

Global context (all templates)

Sidebar context

These variables are only present when the corresponding configuration keys are set in blogmore.yaml:

Pagination context

These variables are present on paginated templates (index.html, tag.html, category.html, archive.html):

pagination_page_urls is the primary way templates link between pages. It is pre-computed by the generator from the page_1_path and page_n_path configuration options and respects the clean_urls setting.

Global context — pagination helpers

Available in every template (including post pages, static pages, etc.):

This variable lets templates construct tag and category listing URLs without hard-coding the pagination scheme. For example:

<a href="/{{ tag_dir }}/{{ safe_tag }}/{{ pagination_page1_suffix }}">{{ tag }}</a>

With the default page_1_path: index.html this produces /tag/python/index.html, or /tag/python/ when clean_urls is enabled.

Template-specific context

Post object

Post objects are passed to templates as items in all_posts, prev_post, and next_post.

Helper methods available on Post:

Draft post visual indicator

When post.draft is True, the built-in templates automatically apply a clear visual indicator to the post title wherever it is rendered:

• The post title is displayed in the draft title colour (--draft-title-color CSS custom property, default amber #cc6600).
• A 🚧 emoji is appended after the title text.
• The containing <article> element receives the CSS class draft-post (for summary cards and individual post pages) or the link receives the class draft-title (in the date archive list).

This applies in every listing context (home page, tag pages, category pages, date archive) as well as on the individual post page. Non-draft posts are never affected.

Custom templates that render post.title should replicate this pattern. A minimal implementation:

<h2><a href="{{ post.url }}">{{ post.title }}{% if post.draft %} 🚧{% endif %}</a></h2>

To override the draft title colour, set --draft-title-color (and --dark-draft-title-color for dark mode) in your custom stylesheet. See Theming for the full CSS variable reference.

Modified date display

When post.modified_date is set, the built-in templates render it after the publication date:

2026-04-27 08:40:40 UTC+01:00 (Modified: 2026-04-28 09:40:40 UTC+01:00)

The modified portion is wrapped in a <span class="modified-date"> element and styled in italics by default. The colour is controlled by the --modified-date-color CSS custom property (defaults to --text-secondary). Override it in your custom stylesheet:

.modified-date {
    --modified-date-color: #888;
}

Custom templates that render post.date should replicate this pattern:

<time datetime="{{ post.date.isoformat() }}">{{ post.date|format_date }}</time>
{% if post.modified_date %}<span class="modified-date"> (Modified: {{ post.modified_date|format_date_plain }})</span>{% endif %}

The format_date_plain filter formats a datetime as plain text (no archive links), making it appropriate for the modified date where archive links would be misleading.

Page object

Page objects represent static pages from the pages/ directory.

Backlink object

Backlink objects are passed to post.html via the backlinks context variable when with_backlinks is enabled. Each entry represents one post that links to the currently-displayed post.

The backlinks list is always present in the post.html context (even when with_backlinks is false) but will be empty when the feature is disabled or when no other post links to the current post.

BlogStats object

The stats context variable in stats.html is a BlogStats instance. The most template-relevant attributes are listed below.

Calendar objects

The calendar.html template receives a calendar_years variable containing a list of CalendarYear objects in reverse chronological order.

CalendarYear

CalendarMonth

CalendarDay

Template inheritance

All page templates extend base.html. The inheritance chain is:

base.html
├── index.html
├── post.html
├── page.html
├── archive.html
├── tag.html
├── tags.html
├── category.html
├── categories.html
├── search.html
├── stats.html
└── calendar.html

Partial templates included by the above:

_pagination.html macro

The pagination macro in _pagination.html renders the numbered page navigation widget. It is called like this:

{% from '_pagination.html' import pagination %}
{{ pagination(page, total_pages, pagination_page_urls) }}

Template blocks

base.html provides the following blocks that child templates can override:

post.html provides the following additional blocks:

CSS classes used by templates

The following CSS classes are part of the stable template/CSS contract:

Stability policy

What will not change in v2.x

• All context variable names listed in this document.
• All Post and Page attribute names listed in this document.
• All template block names listed in this document.
• The names and semantics of all CSS classes listed in this document.
• The data-theme attribute values ("dark" and "light").
• The --bg-color, --text-color, and all other CSS custom properties listed in Theming.

What may change

• The internal HTML structure of partial templates (elements inside .post-summary, .pagination, etc.) may evolve without a version bump, provided the outer class names and overall semantics are preserved.
• New context variables may be added to any template without notice.
• New CSS custom properties may be added at any time.
• Partial template names prefixed with _ are considered internal and may be renamed in a minor release (though we will try to avoid this).

Breaking change policy

A breaking change is any change that would require a user to update a custom template or stylesheet to maintain the same behaviour. Breaking changes will:

1. Be labelled BREAKING CHANGE in ChangeLog.md.
2. Include step-by-step migration instructions.
3. Only be introduced in a new major version (i.e. v2.x → v3.0), never in a minor or patch release.

Additive changes (new context variables, new CSS custom properties, new template blocks) are backward-compatible and therefore require only a minor version bump at most.