1 min read

pyssg.plugins.collections

Collections plugin: declarative, paginated lists of documents.

A collection is a named, ordered selection of document pages (e.g. blog posts): a pure select predicate picks members, an optional sort_key orders them, and an optional :class:Pagination materializes index pages (page 1 at the route, page N at <route>page/N/). The selected member list is also stashed on build.site_data[<name>] so other templates (a "recent posts" sidebar) can read it.

Like the taxonomy plugin, collections are recomputed deterministically from the final graph during evaluate_collections; index pages are stable-id virtual pages, so the engine's page-set diff cleans pages that vanish and the render cache re-emits a page only when its slice actually changes. This is what keeps an incremental rebuild byte-identical to a full build.

class CollectionItem

One candidate member: the facts a select/sort_key may inspect.

class Pagination

How to split a collection into index pages.

route is page 1's URL (e.g. "/" or "/blog/"); page N>1 lives at <route>page/N/. template is the layout template used to render each index page (it receives page.items and page.pagination).

class CollectionSpec

Declarative definition of one collection.

build_collections(build: Build, specs: tuple[CollectionSpec, ...]) -> None

Evaluate every spec, publish member lists, materialize index pages.

class CollectionsPlugin

Materializes the configured collections each build.

CollectionsPlugin.apply(self, builder: Builder) -> None

collections(*specs: CollectionSpec) -> CollectionsPlugin

Factory used in pyssg.config.py.