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 new environments through the custom_environments key of book.toml. Each new environment is specified by an array [env_key, env_name, env_emph], where env_key, env_name, and env_emph are three strings specifying the environment key, the environment name, and the environment emphasis (more specifically, the string that will be added before and after the environment header, e.g. ** for bold), as defined above. The value of the custom_environments must be an array of such environment-defining arrays.

Consider for example the following configuration:

[preprocessor.numthm]
custom_environments = [
  ["conj", "Conjecture", "*"],
  ["ax", "Axiom", "**"]
]

It defines two new environments:

• a "conjecture" environment with key conj, name "Conjecture", and italic emphasis,
• an "axiom" environment with key ax, name "Axiom", and bold emphasis.

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).