mdbook-numbering

A mdBook preprocessor that adds numbering.

• Adds numbers prior to chapter titles.
• Configurable numbering formats (e.g., "1.", "1.1.", "I.", "A.", etc.).
• Adds numbers to lines in code blocks.

Configuration

Add the following to your book.toml:

[preprocessor.numbering]

Then configure as needed (see NumberingConfig for details), for example:

[preprocessor.numbering]

[preprocessor.numbering.heading] # Configuration for heading numbering
enable          = true
numbering-style = "consecutive"  # "consecutive" or "top"

[preprocessor.numbering.code]    # Configuration for code block line numbering
enable          = true

Or if you don't like the flattened style, which also occupies more lines, you can also write it like this:

[preprocessor.numbering]
heading = { enable = true, numbering-style = "consecutive" }
code    = { enable = true }

Configuration Details

• heading: Configuration for heading numbering.
  • enable: Whether to enable heading numbering. Default is true.
  • numbering-style: The numbering style for headings. Can be either "consecutive" or "top". Default is "consecutive".
    • "consecutive": Top-level headings should have consistent numbering with their chapter numbers. For example:
      • If a chapter is numbered 2, its top-level heading should be # Title (<h1> in HTML).
      • If a chapter is numbered 2.3, its top-level heading should be ## Title (<h2> in HTML).
    • "top": Top-level headings should always be in the form of # Title (<h1> in HTML).
• code: Configuration for code block line numbering.
  • enable: Whether to enable line numbering for code blocks. Default is true.

pulldown-cmark Features

There are several optional features of pulldown-cmark (via Options) that can be enabled via flags. Some features conflicting with mdbook are disabled currently.

These options must be enabled, otherwise some features of mdbook may not work as expected. See pulldown-cmark-to-cmark/#106 for more details.

For example:

• If ENABLE_TABLES is not enabled, tables in markdown files will not be rendered correctly.
• If ENABLE_MATH is not enabled, katex preprocessor will not work correctly.

Updates

0.5.0

• Wrap heading numbers in a <span> element with class numbering and heading for easier styling.

• Store heading numbers in a data-numbering attribute of headings for easier access via JavaScript or CSS.

• Hide sections that are automatically added by mdbook when there is no <h1> heading in a chapter, if heading numbering is enabled and heading.numbering-style is set to consecutive.

  This is done by setting display: none to headings without a data-numbering attribute via CSS. So if you want to keep those sections visible or have other automatically generated headings, you can add a data-numbering attribute to them or override the CSS.

0.4.1

• Fix a bug when there are inline code or inline formulas in chapter titles.
• Show a warning if a heading level is above the chapter level when heading.numbering-style is set to consecutive.

0.4.0

• Support more mdbook features by enabling more pulldown-cmark options.

0.3.1

• Fix misleading configuration examples in README.md.

0.3.0

• Update to support mdbook version 0.5.0 and above.
• Improve warning messages for better clarity.
• No longer skip chapters without chapter numbers when other features are enabled.
• Improve performance when popping heading levels.

0.2.1

• Show a warning if this preprocessor is not set to run after katex preprocessor when katex is used.
• Minor code cleanup and documentation improvements.
• Minify the JavaScript file and the CSS file before including them in the preprocessed markdown.

0.2.0

• Added support for adding line numbers to code blocks using highlightjs-line-numbers.js.

0.1.0

• Initial release with support for adding numbers to chapter titles.

Compatibility

mdBook Version

This preprocessor is compatible with mdbook version 0.5.0 and above.

Note

• Using highlightjs-line-numbers.js to add line numbers to code blocks in the rendered HTML. The license of highlightjs-line-numbers.js is MIT License, and is copied to src/highlightjs/LICENSE.

  Some modifications have been made to the original code to fit into this project.