Crate mdbook_numbering

Expand description

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

Feature	Flag	Enabled
`ENABLE_TABLES`	`1 << 1`	✅
`ENABLE_FOOTNOTES`	`1 << 2`	✅
`ENABLE_STRIKETHROUGH`	`1 << 3`	✅
`ENABLE_TASKLISTS`	`1 << 4`	✅
`ENABLE_SMART_PUNCTUATION`	`1 << 5`
`ENABLE_HEADING_ATTRIBUTES`	`1 << 6`	✅
`ENABLE_YAML_STYLE_METADATA_BLOCKS`	`1 << 7`
`ENABLE_PLUSES_DELIMITED_METADATA_BLOCKS`	`1 << 8`
`ENABLE_OLD_FOOTNOTES`	`(1 << 9) \| (1 << 2)`
`ENABLE_MATH`	`1 << 10`	✅
`ENABLE_GFM`	`1 << 11`	✅
`ENABLE_DEFINITION_LIST`	`1 << 12`	✅
`ENABLE_SUPERSCRIPT`	`1 << 13`	✅
`ENABLE_SUBSCRIPT`	`1 << 14`	✅
`ENABLE_WIKILINKS`	`1 << 15`

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.

mdbook-numbering version	mdBook Version
0.1.0, 0.2.0+	0.4.37+
0.3.0+, 0.4.0+, 0.5.0+	0.5.0+

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

Structs§

CodeConfig: Configuration for code block line numbering.
HeadingConfig: Configuration for heading numbering style.
NumberingConfig: Configuration for the mdbook-numbering preprocessor.
NumberingPreprocessor: mdbook preprocessor for adding numbering to headings and code blocks.

Enums§

NumberingStyle: The numbering style to be used by the mdbook-numbering preprocessor.