Headings¶

prodockit.headings numbers the headings in your document as sections, such as 1, 1.1, and 1.2. The numbers update automatically when you add, remove, or move a heading.

Use it when your document needs numbered sections. Add Cross-references when you also want to link readers to those sections by number and name.

Enable the extension¶

Enable it in zensical.toml:

[project.markdown_extensions."prodockit.headings"]
numbering = "continuous"

continuous carries the numbering across the pages in your Zensical navigation. Use per-document instead when every page should start again at section 1.

Number headings¶

Each # heading starts a main section (1, 2, and so on). A ## heading starts a section inside it (1.1, 1.2, and so on):

# Introduction

## Background

## Scope

# Method

The extension calculates the section numbers, but it does not add them to the visible heading text on the website. Cross-references uses the calculated numbers in links such as “1.1 Background”.

Configure headings¶

Choose how numbering continues¶

The numbering setting accepts two values:

For a multi-page documentation site, set the option in zensical.toml:

[project.markdown_extensions."prodockit.headings"]
numbering = "continuous"

For example, if one page ends at section 3, the next page starts at section 4. This also lets Cross-references show one consistent set of section numbers across the site.

Number appendices¶

Add is_appendix: true to the settings at the top of the page (its front matter) to use letter-based numbering instead of the normal numeric sequence - "A", "A.1", "A.1.1" - once you've enabled continuous numbering (see Reference below). An appendix page doesn't consume a number from the numeric sequence at all, so pages after it aren't left with a gap. Letters are assigned sequentially in nav order - the first is_appendix page becomes "A", the second "B", and so on, independent of how many numbered pages come before them.

For example:

---
is_appendix: true
---

# Glossary

## Terms {: #terms }

a prodockit.refs reference to Terms from another page:

<!-- references.md -->
# References

See \ref{terms} for defined terms.

renders to (a link to glossary.md#terms, shown here as a code block since glossary.md isn't a real page on this site):

<p>See <a class="prodockit-ref" href="glossary.md#terms">A.1</a> for defined terms.</p>

Glossary's own h1 becomes "A" (the first appendix page in nav) and its Terms subheading becomes "A.1" - and References, the page after it, still gets the next plain number in the numeric sequence ("2", not "3"), exactly as if the appendix page had never consumed one. Only meaningful under Zensical; ignored otherwise.

Leave a heading unnumbered¶

A heading with an unnumbered class - e.g. a cover page or title slide - still gets an id, but is skipped when computing section numbers, so it doesn't consume a counter position:

# Cover Page {: .unnumbered }

# Introduction

Introduction above is still numbered 1, as if Cover Page weren't there at all.

Hide a heading from PDF navigation¶

A PDF built by prodockit.pdf has two tables of contents, and unnumbered alone only reaches one of them:

• The generated Table of Contents page, built from every heading Pandoc sees. Add unlisted to also keep a heading off this page - it still keeps its id and number (if any), the same as unnumbered above. Pandoc itself defines this class and honours it via pandoc.structure.table_of_contents(); prodockit doesn't add or change its meaning.
• The bookmark outline - the navigation pane a PDF reader shows down the side. This is built separately by WeasyPrint from every h1-h6 in the document, and unlisted has no effect on it at all. Add unbookmarked to also remove a heading from the outline.

# Cover Page {: .unnumbered .unlisted .unbookmarked }

This distinction matters because outline nesting follows heading level: an unlisted (but not unbookmarked) h1 still becomes a top-level outline node, and every following heading of lower level nests underneath it instead of under its real chapter - not just one stray entry, but a misnested chunk of the outline. See Table of contents and bookmark outline for the underlying stylesheet rule and worked example.

Reference¶

Ids¶

An id comes from one of, in order of precedence:

1. An explicit id set via attr_list, e.g. # Introduction {: #custom-id }.
2. Python-Markdown's own toc extension, which prodockit.headings enables automatically (with its defaults) if you haven't already enabled it yourself - so if you have configured toc (e.g. with permalink: true), that configuration is left untouched and reused.
3. A minimal built-in slugify fallback, used only if toc is somehow not registered at all (this should not normally happen, since prodockit.headings enables it).

Zensical settings¶

Cross-page numbering in Zensical¶

Zensical shares heading information across the complete navigation automatically. With numbering = "continuous", adding or reordering a page updates later section numbers without a manual starting value.

Give repeated headings explicit ids. If several pages each contain ## Quick start, their automatically generated ids collide and the build warns; which page renders first is not a stable way to choose a link target:

## Quick start {: #refs-quick-start }

For integration with another Markdown renderer, see Extension integration.

Customise with a CSS style sheet¶

prodockit.headings doesn't add any class of its own to a heading - only an id (see above), the class(es) already on the heading (e.g. unnumbered), and whatever numbers are consumed by prodockit.refs. There is no prodockit-heading-style class to hook a stylesheet onto directly.