Website macros¶

prodockit.zensical_macros provides a handful of Jinja variables and macros for Zensical's own macros plugin - the pieces a professional/academic report's website commonly wants that aren't specific to any one project: a site-wide word count, the git-detected repository URL, the successfully applied template release, chapter/appendix numbering that continues across pages, and reference/acronym/glossary list spacing that matches prodockit.pdf's own PDF output.

Quick start¶

Add it alongside your own project's macros.py (which keeps anything genuinely project-specific - a custom macro, institution branding, and so on):

[project.markdown_extensions.zensical.extensions.macros]
module_name = "macros"
modules = ["prodockit.zensical_macros"]
on_error_fail = true

Zensical's macros plugin loads module_name and every entry in modules, merging all of their variables/macros into the same Jinja environment - so a project with no macros of its own can drop module_name/macros.py entirely and just use:

[project.markdown_extensions.zensical.extensions.macros]
modules = ["prodockit.zensical_macros"]
on_error_fail = true

Keep on_error_fail = true in automated and local builds. If Jinja cannot render a page variable or macro call, Zensical then stops the build instead of returning the unrendered page and allowing a broken site to be published.

Variables¶

Zensical already exposes project configuration through config and repository metadata through git. Prodockit adds only values with different semantics. Use the pdk_ prefix for its public names to avoid collisions with project and plugin names. The old unprefixed names remain temporarily for compatibility; old macro calls emit a deprecation warning. The values used by Prodockit projects are listed in Table 29.1.

Why pdk_repo_url and pdk_applied_release remain Prodockit variables¶

Zensical's built-in macro context already exposes the project configuration through config and repository metadata through git. Prodockit uses native values such as config.site_name and git.short_tag where their semantics match. The two variables below deliberately add behaviour that those values do not currently provide. See Zensical's built-in template variables for the native interface they complement.

{{ pdk_repo_url }} describes the checkout being built, not only the URL last written to zensical.toml. It reads the active origin, converts Git's SSH form to an ordinary HTTPS link, and removes embedded CI credentials before the value reaches generated HTML. This keeps a fork or mirror pointing at its real repository and prevents a token-bearing clone URL from becoming a public link. The native config.repo_url remains the right choice when the configured value is intentionally different from the active checkout.

{{ pdk_applied_release }} records the version of prodockit-template most recently applied successfully, not the latest tag in the student's repository. The native git.short_tag is therefore the right value for the document's own release but cannot describe its template state. Keeping these meanings separate lets maintainers see whether a project has successfully received a template fix even after the project creates its own tags.

The prefixed Prodockit names are stable author-facing interfaces. If a future Zensical release provides the same normalized, credential-safe repository URL or an equivalent persisted template-release value, Prodockit will implement the matching variable as a compatibility alias to Zensical's native value. Authors will not need to rewrite existing {{ pdk_repo_url }} or {{ pdk_applied_release }} expressions, while Prodockit can stop maintaining duplicate discovery logic.

Macros¶

Table 29.2 lists the callable helpers and the content each one inserts.

Show macro syntax as text¶

The macros plugin processes Jinja delimiters before Markdown code formatting. Backticks therefore do not protect a literal macro example. A literal {{ pdk_word_count }}, GitHub expression, or compact {#heading-id} example can stop every macro on that page from being rendered.

When readers should see the syntax rather than run it, wrap the literal text between {% raw %} and {% endraw %} in the Markdown source. For example:

{% raw %}
{{ word_count }}
${{ github.token }}
{#heading-id}
{% endraw %}

The raw wrapper is removed from the website and the intended braces remain. Use an unwrapped expression when it is meant to run.

pdk_heading_counter_reset(page)¶

Continues heading numbering from wherever the previous page left off. The numbering stays aligned with \ref{} links and updates when pages are reordered or headings are added or removed.

Set project.extra.heading_numbering = false in zensical.toml to turn numbering off entirely (content and sidebar) across the whole site. A page flagged is_appendix: true in its own front matter gets letter-based numbering instead - "Appendix A", "A.1", "A.1.1" - matching prodockit.headings' own appendix_attr default.

Contributors changing how page numbers are discovered should read Extension integration.

pdk_reference_style() / pdk_acronym_style() / pdk_glossary_style()¶

Controls list-entry spacing, driven by the same project.extra.* settings prodockit.pdf reads for the PDF, so both outputs stay in sync from one configured value:

Table 29.3 shows which configured style value each helper returns.

For supported versions and the pre-1.0 stability boundary, see Support and compatibility.

Page dates are not macros¶

Build-derived dates do not require the macros plugin. Use Page update dates to choose where a website date appears, write its accompanying text, or override one page's automatic date.