mdbook-numeq

An mdBook preprocessor to automatically number centered equations and later create a link to these equations for a "LaTeX" type experience.

Installation

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

$ cargo install mdbook-numeq

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

[preprocessor.numeq]

This crate uses the htmlID command which is disabled by default. It must enabled by adding trust = true to the options of the mdbook-katex preprocessor:

[preprocessor.katex]
trust = true

Usage

Just add {{numeq}} at the end of your centered equation, e.g. (assuming you set the delimiters for centered equations to \[ ... \] in the mdbook-katex preprocessor options)

\[
 a= b {{numeq}}
\]

and your equation will be automatically numbered:

a = b           (1)

You can optionally provide a label {{numeq}}{mylabel}, in which case an anchor will be created. You can then link to the equation using {{eqref: mylabel}}.

Options

By default, the numbering is per (sub)chapter, meaning the counter is reset to zero at the beginning of each (sub)chapter. You can choose a global numbering throughout the book by setting the global option to true:

[preprocessor.numeq]
global = true

Then, equations will be numbered, say, 1 to 5 in Chapter 1, then 6 to 9 in Chapter 2, etc.

You can choose to add the chapter number as a prefix to the counter by setting the prefix option to true (which makes more sense when global is false, but both options are independent).

[preprocessor.numeq]
prefix = true

For example, in Chapter 3.2, equations will then be numbered 3.2.1, 3.2.2, etc.

Additionally, the depth option controls how many layers of prefix should be applied. Leaving it unspecified or setting depth = 0 means the full prefix is always used. Setting, e.g., depth = 1, equations will be numbered 3.1, 3.2 etc. throughout Chapter 3 and all its subchapters. Note that prefixes are always depth-long and trailing zeros are added if needed (e.g., if depth = 3 then prefix 3.0.0 is used in Chapter 3, prefix 3.1.0 is used in Chapter 3.1, etc.)

Although it should only make sense to use depth strictly larger than 0 with prefix = true, these two options are independent. Note that when depth is set to any number strictly greater than 0, option global is ignored and the equation counter is reset for each prefix. This means that setting

[preprocessor.numeq]
global = true
prefix = false
depth = 1

is equivalent to

[preprocessor.numeq]
global = false
prefix = false

and the equation counter is reset for each (sub)chapter and no prefix is prepended.