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 result in Table 20.1 shows the numbering the extension also supplies to Cross-references. The shared prodockit website styles can also show those numbers beside headings and in the page navigation. This reference site has that presentation enabled, so the example headings on this page are visibly numbered.

Configure headings¶

Configuration decides whether numbering continues across pages, where a page's counter starts, and which headings are deliberately excluded. The following subsections cover those choices in that order.

Choose how numbering continues¶

The numbering setting accepts two values:

Table 20.2 compares page-by-page numbering with numbering that continues across the site.

Choose the continuation behaviour from Table 20.2, then set it 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 }

The appendix result in Table 20.3 is also used by 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

In Table 20.4, Introduction 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¶

Use this section to look up id generation and the complete Zensical settings after choosing the numbering behaviour in the worked examples.

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¶

The numbering modes and their defaults are collected in Table 20.5.

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.