Expand description
Taxonomy generation plugin.
Reads tags and categories from frontmatter sidecars and
generates index pages for each taxonomy term, rendered through
the same template engine (MiniJinja) that drives normal page
rendering. Built-in fallback templates extend base.html so the
pages share the site’s layout, CSS, nav, and footer (#542).
§Per-term landing pages (issue #586, port 5 of 5)
Besides the /tags/index.html hub, every term gets its own
landing page (/tags/<slug>/index.html, and likewise for
categories and topics) listing its member posts. Terms may be
declared either as frontmatter arrays (tags: [a, b]) or as the
comma-separated string form the bundled examples use
(tags: "a, b, c"). Slugs come from ssg_core::slugify;
term ordering is case-insensitive alphabetical, so output is
deterministic across rebuilds.
§Lifecycle caveat — the transform_html bypass
This plugin writes pages in after_compile, but the pipeline
snapshots the HTML file list before after_compile runs
(pipeline.rs: cache_html_files() precedes
run_after_compile()), so the fused transform_html pass never
sees taxonomy pages — canonical/JSON-LD/a11y transform plugins
skip them (the ROADMAP-documented plugin-lifecycle-phase trap;
see #586). Mitigation: the built-in templates (and the
non-templates fallback renderer) inline the essential head
elements themselves — <!DOCTYPE html>, <html lang>,
<meta charset>, <title>, a <link rel="canonical"> derived
from site.base_url + the term’s directory URL, plus the SEO
meta the audit gates probe (description, og:title,
og:type, og:description, og:url, twitter:card). Pages
generated here therefore do not depend on the transform chain
for correctness; richer per-page structured data (JSON-LD,
og:image) stays with the full taxonomy engine planned for
0.0.48 (#587).
Two further real-pipeline behaviours: sidecars are read from
<build>/.meta/ with a fallback to the staged <site>/.meta/
copy, and author-authored pages (e.g. a hand-written
/tags/index.html compiled from tags.md — anything without
the ssg-taxonomy generator marker) are never overwritten.
Structs§
- PageRef
- One page as a taxonomy lists it.
- Taxonomy
Plugin - Plugin that generates taxonomy index pages for tags and categories.
- Taxonomy
Term - A taxonomy term with its associated pages.