/mdbook-numthm

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

Primary LanguageRustMIT LicenseMIT

mdbook-numthm

Crates.io GitHub License

An mdBook preprocessor for automatically numbering 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.

Configuration

For now, environments are fixed by defaults to:

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

Each environment is numbered independently. For example,

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

will yield

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

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.

TODO

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