mdbook-numthm

An mdBook preprocessor to automatically number theorems, lemmas, etc.

If you're used to writing maths with LaTeX, using mdbook might be frustrating if you plan to have a lot of theorems, lemmas, definitions, etc. that you'd like to automatically number and later link to. This preprocessor kind of provides what the amsthm package does for LaTeX.

You can see it in action here.

Installation

Assuming you have mdBook and mdbook-katex installed, install the crate with

$ cargo install mdbook-numthm

Then add it as a preprocessor to your book.toml:

[preprocessor.numthm]

Usage

An environment consists of a key (an arbitrary string), a name (such as "Theorem", "Lemma", etc.), and some emphasis to be applied to the header.

It will replace all occurrences of

{{key}}{label}[title]

into an anchor identified by label followed by a header consisting of the name of the environment, an automatically generated number, and the title in parentheses.

Fields label and title are optional. If no label is provided, then no anchor will be created, and if no title is provided, then no title will be displayed in the header. If a label already exists, it will ignore it and emit a warning.

For example, for the "theorem" environment, the key is thm, the name is Theorem, and the emphasis of the header is bold. Hence, this:

{{thm}}{thm:central_limit}[Central Limit Theorem]

will become (assuming this is the first occurrence of the key thm)

<a name="thm:central_limit"></a>
**Theorem 1 (Central Limit Theorem).**

and will be rendered as

Theorem 1 (Central Limit Theorem).

All environments that received a label can be referred to by creating a link using

{{ref: label}}

It will be replaced by a markdown link

[Theorem 1](path/to/file.md#label)

If the environment had a title, it can be used in place of "Theorem 1" by using

{{tref: label}}

which will be replaced by

[Central Limit Theorem](path/to/file.md#label)

If the label does not exist, it will replace the ref with [??] and emit a warning.

Builtin Environments

Five builtin environments are provided:

• theorem: key thm, name Theorem, bold emphasis
• lemma: key lem, name Lemma, bold emphasis
• proposition: key prop, name Proposition, bold emphasis
• definition: key def, name Definition, bold emphasis
• remark: key rem, name Remark, italic emphasis.

Numbering

Each environment is numbered independently. For example,

{{thm}}
{{lem}}
{{lem}}
{{thm}}
{{lem}}

will yield

Theorem 1. Lemma 1. Lemma 2. Theorem 2. Lemma 3.

Moreover, the counter for each environment is reset at the beginning of each (sub)chapter.

Custom Environments

It is possible to define or change environments through the environments table numthm in book.toml.

Each new environment is specified by an entry of the form key = {name = "name", emph = "*"}, where

• key specifies the environment key
• name specifies the environment name
• emph specifies the environment emphasis. More specifically: the string that will be added before and after the environment header, e.g. ** for bold.

Consider for example the following configuration:

[preprocessor.numthm.environments]
conj = {name = "Conjecture", emph = "*"}
ax = {name = "Axiom", emph = "**"}
thm = {emph = "*"}    # redefine a builtin
lem = {ignore = true} # ignore parsing an environment (builtin or not)

It does the following:

• define a new "conjecture" environment with key conj, name "Conjecture", and italic emphasis,
• define a new "axiom" environment with key ax, name "Axiom", and bold emphasis,
• redefine the builtin "theorem" environment by changing emphasis to italic,
• instruct the preprocessor to ignore all "lemma" environments.

Configuration

There is a single configurable option

[preprocessor.numthm]
prefix = bool

If prefix is set to true, the environment numbers will be prefixed by the section number. For example, in Chapter 1.2, theorems will get numbered 1.2.1, 1.2.2, etc.

Interaction with other Preprocessors

If you're also using the [mdbook-footnote] preprocessor, you must ensure that it is run after mdbook-numthm:

[preprocessor.footnote]
after = ["numthm"]

TODO

• allow common numbering of some subsets of environments (e.g., theorems and lemmas get a common counter and definitions get an independent one).