Numbering¶

Every key, with its type and default: [build.numbering].

The [build.numbering] table decides which items carry a number — sections, figures, tables, code blocks and equations — how a number is written, and the text a numbered reference (:numref:, :eq:) prints. It is one model, computed once for the whole project, that ubc check, the editor and both builds start from (in the editor and for agents).

Each builder has a table of its own, [build.html.numbering] and [build.pdf.numbering]. It takes the same keys, inherits every key it does not set from [build.numbering] and wins on every key it does — so a printed manual can be numbered throughout while the site is not. Only the builder tables have the two presentation keys, suffix and show, which say how and where that output prints a number.

With nothing configured, ubCode numbers what Sphinx numbers by default: the sections of the documents a :numbered: toctree lists, and every labelled display equation (restarting on every page). Figure, table and code-block captions are numbered only when you switch them on.

[build.numbering]
sections = { from = "all", depth = 3 }   # number every chapter, three levels deep
figure = { enabled = true }              # Fig. 1.1, Fig. 1.2 …
table = { enabled = true }
code = { enabled = true }

[build.html.numbering]
show = { sidebar = true }                # numbers in the site navigation too

Sections¶

sections.from

Which documents’ sections are numbered.

"toctree" (the default) is Sphinx’s rule: the documents a :numbered: toctree lists are numbered, with their sections and the documents their own toctrees list. The document holding the numbered toctree is not numbered itself, and every numbered toctree starts again at 1 (so Part I and Part II can each hold a numbered toctree of chapters). Documents and sections share one count, in document order: a toctree written inside section 2.3 numbers its documents 2.3.1, 2.3.2 …. :hidden: toctrees number like visible ones; :maxdepth: and :titlesonly: change only what a list displays.

"all" numbers as if every toctree of the root document said :numbered:. The root document itself is not numbered — unless it lists no documents at all (a one-page project), in which case its own sections are numbered, the sections under its title being level 1. :numbered: on any other toctree is then ignored.

"none" numbers no section, and ignores :numbered:.

sections.depth

How many levels are numbered. 0 (the default) numbers as deep as each :numbered: N says, or every level with from = "all". A number above zero numbers levels 1 to N only, whatever :numbered: says. Level 1 is the titles of the documents a numbered toctree lists.

sections.pattern

How a section number is written. Defaults to "1.1". Write one counter style per level — 1 arabic, a / A letters, i / I roman numerals — separated by the text to print between levels; the last style repeats for every deeper level. "I.A.1" prints II.B.3; "1.a" prints 2.b.c. Letters continue past z as aa, ab …, and every separator in one pattern must be the same text. Figure, table, code and equation numbers write their section prefix in these styles and their own count in arabic.

sections.reference

The :numref: text for a section. Defaults to "Section {number}". A list gives one template per level, the last repeating: ["Chapter {number}", "Section {number}"].

sections.appendix

Appendix lettering for ubc build pdf’s [build.pdf] appendices: pattern (default "A.1") and reference (the text for the appendix itself, default "Appendix {number}"). The HTML site has no appendices, and prints no appendix numbers. Lettering applies only when sections are numbered. An appendix is numbered as deep as the body: to sections.depth when it is set, else to the deepest :numbered: N of the root document’s numbered toctrees (every level for a bare :numbered: or from = "all"), and the documents an appendix’s own toctrees list are numbered inside it (A.1).

An entry a toctree of the body already lists, :hidden: included, is no appendix: the PDF prints it where the body does, and it is never lettered.

ubc build pdf reports a :numref: against its own numbers, so a reference the PDF numbers on a page only [build.pdf] appendices reaches (the lettered appendix, Appendix A; a figure its figure numbering covers, Fig. A.1; a section within the numbered depth) is not reported. ubc check, the editor and ubc build html still report it as std.numref_not_numbered (its document is not reached from the root document): the shared model and the site have no appendices, and the site prints no number for it. Under the default --deny warning that fails ubc build html. To build the site anyway, silence the code for that run, ubc build html --lint-extend-ignore std.numref_not_numbered, or silence those references in every run with a [[lint.message-ignores]] rule matching their labels (which quiets them in ubc check and the editor too):

[[lint.message-ignores]]
codes = ["std.numref_not_numbered"]
contains = "'fig-appendix-overview'"

A :numref: to an entry the body lists is reported with the body’s reason — its document is not listed by a :numbered: toctree for one a plain or :hidden: toctree lists — and that reason holds in the PDF too.

To leave one section out, give it the class unnumbered. It takes no number and does not consume one, and neither do its subsections; on a document’s title, the whole document is left out, with the documents its toctrees list, and the documents after it are numbered as if it were not there. Figures, tables, code blocks and equations inside it are still numbered, with the prefix of the nearest numbered section around them. On a page whose title is unnumbered that is the section whose toctree lists the page: listed from inside section 1.1, its figures are Fig. 1.1.1, Fig. 1.1.2 … (with within = 2); listed straight from the root’s numbered toctree, they have no prefix (Fig. 1). Sphinx keeps the class and numbers the section anyway, so the spelling is safe in a project that is also built with Sphinx.

reStructuredText

.. rst-class:: unnumbered

Preface
=======

MyST

{.unnumbered}
# Preface

Figures, tables and code blocks¶

[build.numbering.figure], [build.numbering.table] and [build.numbering.code] take the same four keys. A figure is numbered when it has a caption, and so is a diagram (uml, plantuml, mermaid) with a :caption:: when a build cannot draw one, the placeholder it shows instead still prints its caption and number; a table when it has a title (.. table:: Title, a list-table or csv-table argument, a Markdown table’s caption); a code block when it has a :caption:. An item without one is not numbered and does not consume a number, and neither is one with the class unnumbered (:class: unnumbered on a table or code block, :figclass: unnumbered on a figure). An item with no :name: is numbered too, and a label written immediately before it (.. _fig-x:) names it as a :name: does.

enabled

Number the captions of this kind. Off by default.

within

What prefixes the number, and where its count restarts. 1 (the default) prefixes the number of the enclosing section, truncated to one level, and restarts the count for every chapter (Fig. 2.3); 2 uses two levels (Fig. 2.1.3). 0 is one count over the whole project (Fig. 17). "document" restarts on every page with no prefix.

A prefix needs numbered sections. An item in an unnumbered part of a document — the root document, or a page no numbered toctree lists — shares the one unprefixed count, so Fig. 1 and Fig. 2 can sit beside Fig. 1.1; and a project with no numbered section at all numbers every item in one count, whatever within says. An item on a page the root document does not reach has no number.

caption

The label printed before the caption text. Defaults to "Fig. {number}" ("Table {number}", "Listing {number}").

reference

The :numref: text. Defaults to the caption label’s default.

An item that a build leaves out — an only block whose tags are false, a variant’s excluded content — is not counted: the numbers have no gaps, but an HTML site and a PDF built with different build_tags may number differently.

Equations¶

[build.numbering.equation]:

enabled: Number labelled display equations — on by default. A math block with a :label: (else a :name:, or a MyST (label)) prints (N) beside it, and :eq: refers to it. Turned off (or with [build.numbering] enabled = false), no equation is numbered, and an :eq: to a labelled one still links to it, with the label as its text.
all: Number unlabelled display equations too. Off by default.
within: The same values as a figure’s within. Defaults to the figure table’s within when figure numbering is on, and to "document" (start again at (1) on every page) when it is off.
separator: The text between an equation’s section prefix and its own count: "." (the default) prints (2.4), "-" prints (2-4).
reference: The :eq: text. Defaults to "({number})".

Only an equation this table numbers carries a number. An unlabelled block (unless all = true) prints none, and neither does an environment the author writes inside the maths itself — an unstarred equation or align — as Sphinx’s default MathJax draws none; an explicit \tag{…} is still drawn, as MathJax draws it. A MyST amsmath block is the exception: Sphinx with MyST-Parser numbers each unstarred environment in the equation sequence, one number per environment, where ubCode prints none unless all = true (a difference).

Templates¶

A caption or reference template is text with two placeholders: {number} (or Sphinx’s %s) is the number, and {name} the caption text or section title. They are recognised exactly as written; {{ and }} print a brace. A template must contain {number}, and anything else in braces is refused when the configuration is read — naming the key, rather than failing the build halfway.

A :numref: role’s own title is a template too: :numref:`Figure {number}: {name} <fig-x>` prints Figure 1.2: The caption. A title with no placeholder is used as the link text as written.

Where numbers are printed¶

[build.html.numbering] and [build.pdf.numbering] each have:

suffix: The text after a section number in a heading or a list: ". " on the site (1.2. Title), nothing in the PDF, which sets its own gap. It is never part of a reference’s {number}.
show: Which surfaces print numbers. On the site: headings, captions, equations, toctree (a page’s own toctree lists) and page_toc (the “on this page” contents) are on; sidebar, prev_next and title (the browser tab) are off — numbers belong to the content, not the site’s chrome. In the PDF: headings, captions, equations, toc, outline (the bookmarks) and running_head are all on. Turning equations off hides the number beside a numbered equation; it does not hand the equation back to the maths engine, so the block shows no number at all, on the site as in the PDF.

enabled = false in a builder table turns every number off in that output; a numbered reference there prints the target’s title instead.

Numbered references¶

:numref: (and MyST {numref}) refers to a numbered figure, table, code block or section by its label — the label is matched ignoring case, as in Sphinx — and prints the kind’s reference text, or the role’s own title. :eq: (and {eq}, :math:numref:) refers to an equation by its label, matched exactly, and prints equation.reference; a title is ignored. :ref: and :doc: never print a number.

A reference whose target has no number still links to it, with the target’s title or caption as its text, and reports why there is no number (std.numref_not_numbered): the kind is not numbered, the item has no caption or is marked unnumbered, its page is not under a numbered toctree, or the root document does not reach it. A label that does not exist is std.numref; an :eq: label that does not exist is std.eq (:math:numref: reports nothing, as in Sphinx).

An :eq: to an equation with no number links to it with the label as its text. When equation numbering is on and the equation has no number — it is marked unnumbered, or the root document does not reach its page and its within is not "document" — the reference reports why (std.eq_not_numbered); with equation numbering turned off it reports nothing, since no equation has a number to print. :math:numref: reports neither.

ubc check and the editor’s diagnostics compute these findings against the shared [build.numbering] model. A builder table that numbers differently changes what that builder prints: a reference there uses that builder’s numbers, and prints the target’s title where that builder gives it none. So ubc build html and ubc build pdf each report std.numref_not_numbered, std.eq and std.eq_not_numbered against the numbers that build prints ([build.html.numbering], or [build.pdf.numbering] with the PDF’s appendices): a reference that build numbers is not reported, and one it leaves unnumbered is. Its advice names that builder’s table when the setting the reason is about is set differently there from [build.numbering] (figure numbering is off (`[build.pdf.numbering.figure] enabled = true` turns it on)), and [build.numbering] otherwise. A build can therefore report a reference ubc check does not, and the other way round. toctree.secnum is always the shared model’s.

In the editor and for agents¶

VS Code Any LSP editor MCP Beta

In a reStructuredText document, the language server answers a numbered reference from the project’s last index pass:

Hover on a :numref:, :eq: or :math:numref: shows the number ubc build html prints — the [build.html.numbering] model, which the Rendered preview prints too. A :numref: shows the target kind’s reference text (not the role’s own title) with the target’s caption or title beside it; an equation shows its label, its page and the file:line it is written on. A target with no number shows why instead: the shared [build.numbering] model’s reason, in the words ubc check uses where it reports one — or, when only [build.html.numbering] leaves the target unnumbered, the html build’s reason, which names that table. A missing equation label shows std.eq’s message, for :math:numref: too.
Go to definition on an :eq: or :math:numref: opens the math block that carries the label, on its :label: (or :name:) line, or a MyST $$ block’s first line — in the included file when the equation is written in one. :numref: goes to its label, as :ref: does.

The hover and ubc check can disagree when the two tables differ: where [build.html.numbering] numbers what [build.numbering] does not, the hover shows the number the site prints while the squiggle reports the shared model’s “no number” (and ubc build html reports nothing); where [build.numbering] numbers what [build.html.numbering] does not, the hover gives the html build’s reason while ubc check reports nothing (and ubc build html reports that reason). The hover and the squiggle never read [build.pdf.numbering] or the PDF’s appendices, so neither shows what only the PDF numbers.

Hover and go to definition do not work on MyST roles ({eq}, {numref}) yet.

For an AI agent, the MCP tool resolve_reference takes the roles numref, eq and math:numref, and answers with the same number and the same reason; a missing equation label carries no suggestions (see its reference).

Coming from Sphinx¶

Sphinx’s numbering settings live in conf.py, which ubCode does not read. Each has one home here:

Sphinx	`ubproject.toml`
toctree `:numbered:` / `:numbered: N`	honoured as written when `sections.from = "toctree"` (the default)
`numfig`	`figure.enabled`, `table.enabled` and `code.enabled`
`numfig_secnum_depth`	`figure.within`, `table.within`, `code.within`
`numfig_format['figure' \| 'table' \| 'code-block']`	`<kind>.caption` and `<kind>.reference`
`numfig_format['section']`	`sections.reference`
`math_numfig`	`equation.within` (its default follows `figure`)
`math_numsep`	`equation.separator`
`math_number_all`	`equation.all`
`math_eqref_format`	`equation.reference`
`html_secnumber_suffix`	`[build.html.numbering] suffix`
`latex_appendices`	`[build.pdf] appendices` with `sections.appendix`
LaTeX `secnumdepth`	`[build.pdf.numbering] sections.depth`

Where ubCode numbers differently from Sphinx, on purpose:

Numbered toctrees are taken in document order. Sphinx processes them in an order that changes from run to run, so overlapping numbered toctrees can number differently on every build. ubCode takes them in the order the toctrees reach the documents, and reports a document a second numbered toctree reaches as toctree.secnum.
Content a build leaves out is not counted (only, variants), where Sphinx counts it and leaves gaps.
Each kind is switched on its own, where numfig switches all three, and the caption label and the reference text are two settings, where numfig_format is one.
A bad template is a configuration error, where Sphinx’s build crashes; a :numref: title without a placeholder is plain link text, where Sphinx drops the number or fails.
The PDF is numbered like the site, where Sphinx’s LaTeX output numbers every section and caption regardless of :numbered: and numfig. [build.pdf.numbering] turns that back on for print alone (PDF document).
The class unnumbered leaves a section or item out; Sphinx ignores it.
A :numbered: toctree on a page the root document does not reach numbers nothing (an :orphan: page, say), where Sphinx numbers the documents it lists: numbering walks from the root document.
The site’s navigation and page title carry no numbers by default (show.sidebar, show.prev_next, show.title).