1 min read

pyssg.contrib.publish_gate

Contrib plugin: gate which documents are published, by frontmatter flag.

Selective publishing for a personal-knowledge-base or draft workflow: only the notes you mark are turned into pages, the rest stay private. The decision is read from a single frontmatter key (publish by default) and enforced through the route hook -- a suppressed document routes to the empty string, so the permalink generator emits no page for it (and nothing links to a 404).

Two modes:

• allowlist (publish_required=True, the default): a document is published only when its flag is truthy (publish: true). This mirrors Obsidian Publish and is the safe default -- a note is private unless you opt it in.
• denylist (publish_required=False): every document is published except those whose flag is explicitly false (publish: false), i.e. opt-out.

It taps route at a late stage so its veto is final, after any other plugin (e.g. i18n) has shaped the URL. The decision is a pure function of the document's frontmatter and the static mode, so builds stay byte-identical and incremental rebuilds equal full rebuilds; the mode and key are folded into cache_version.

should_publish(meta: dict[str, object], *, key: str, publish_required: bool) -> bool

Whether a document with these frontmatter meta values is published.

In allowlist mode (publish_required=True) the key value must be truthy. In denylist mode it is published unless the value is explicitly False.

class PublishGatePlugin

Suppresses pages for documents not selected for publishing.

PublishGatePlugin.__init__(self, *, key: str = 'publish', publish_required: bool = True) -> None

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

publish_gate(*, key: str = 'publish', publish_required: bool = True) -> PublishGatePlugin

Factory used in pyssg.config.py.

key is the frontmatter field to read (default "publish"). publish_required selects allowlist (default) vs denylist mode.