Section Numbers

Turn on section numbers

Sections aren’t numbered by default. However, you can enable this feature by setting the attribute sectnums.

= Title

When sectnums is set, level 1 (==) through level 3 (====) section titles are prefixed with arabic numbers in the form of 1., 1.1., etc. Section numbers can be set and unset via the document header, CLI, and API. Once you’ve set sectnums, you can reduce or increase the section levels that get numbered in the whole document with the sectnumlevels attribute. You can also control whether a section is numbered on a section by section basis.

Toggle section numbers on or off per section

The sectnums attribute is a unique attribute. It’s a flexible attribute, which means it can be set and unset midstream in a document, even if it is enabled through the API or CLI. This allows you to toggle numbering on and off throughout a document.

To turn off numbering for one or more sections, insert the attribute above the section where you want numbering to cease and unset it by adding an exclamation point to the end of its name. To turn section numbering back on midstream, reset the attribute above the section where numbering should resume.

= Title

== Numbered Section


== Unnumbered Section

== Unnumbered Section

=== Unnumbered Section


== Numbered Section

For regions of the document where section numbering is turned off, the section numbering will not be incremented. Given the above example, the sections will be numbered as follows:

1. Numbered Section

Unnumbered Section

Unnumbered Section

Unnumbered Section

2. Numbered Section

The section number does not increment in regions of the document where section numbers are turned off.

sectnums order of precedence

If sectnums is set on the command line or API, it overrides the value set in the document header, but it does not prevent the document from toggling the value for regions of the document.

If it is unset (sectnums!) on the command line or API, then the numbers are disabled regardless of the setting within the document.

Number special sections

Sections that are assigned a built-in special style are not numbered by default. To number regular sections as well as special sections, set sectnums and assign it a value of all.

= Title
:sectnums: all

The assignment of appendix numbers isn’t affected by sectnums as their section title prefixes are controlled by the attribute appendix-caption. Book parts aren’t numbered by sectnums either, instead, they’re controlled by partnums.

Number book parts

Book parts are assigned roman numerals when the attribute partnums is set.

= The Secret Manual
:doctype: book

= Defensive Operations

== An Introduction to DefenceOps

= Managing Werewolves

When rendered, part numbers are displayed as roman numerals.

I. Defensive Operations
1. An Introduction to DefenceOps
II. Managing Werewolves

Specify the section levels that are numbered

When sectnums is set, level 1 (==) through level 3 (====) section titles are numbered by default. You can increase or reduce the section level limit be setting the sectnumlevels attribute and assigning it the section level you want it to number. The sectnumlevels attribute accepts a value of 0 through 5, and it can only be set in the document header.

= Title
:sectnumlevels: 2 (1)
1 When the sectnumlevels attribute is assigned a value of 2, level 3 through 5 section titles are not numbered.

Recall that when the doctype is book, level-1 sections become chapters. Therefore, a sectnumlevels of 4 translates to 3 levels of numbered sections inside each chapter.

Assigning sectnumlevels a value of 0 is effectively the same as disabling section numbering (sectnums!). However, if your document is a multi-part book with part numbering enabled, then you’d have to set sectnumlevels to -1 to disable part numbering too (the equivalent of partnums!).