mkdocs-enumerate-headings-plugin 0.1

MkDocs Plugin to enumerate the headings (h1-h6) in a MkDocs site

mkdocs-enumerate-headings-plugin

MkDocs Plugin to enumerate the headings (h1-h6) in a MkDocs site

Features :star2:

• Automatically numbers all headings and gives each page an sequential chapter number
• Compatible with plugins like awesome-pages and monorepo
• Compatible with markdown_extensions: pymdownx.snippets
• Easy to customize styling through CSS

Setup

Install the plugin using pip:

pip3 install mkdocs-enumerate-headings-plugin

Next, add the following lines to your mkdocs.yml:

plugins:
  - search
  - enumerate-headings

If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set.

Usage

There is only one requirement: make sure each markdown page starts with a level 1 header (#). Pages with no headings and pages with multiple h1 headings are allowed.

Note this plugin only affects your rendered HTML and does not affect the markdown files.

Styling

All heading numbers are wrapped in <span class='enumerate-headings-plugins'></span> and can be customized using CSS. See MkDocs documentation for customizing a theme on how to add an CSS to your theme.

As a suggestion here is some CSS that makes the numbers slightly lighter than the heading:

/* Extra CSS for mkdocs-enumerate-headings-plugin */ 
.enumerate-headings-plugins {
  /* 100% is baseline so 250% is a lot lighter */
  filter: brightness(250%);
}

Options

You can customize the plugin by setting options in mkdocs.yml:

plugins:
    - enumerate-headings:
        strict: true

• strict (default true): Raise errors instead of warnings when first heading on a page is not a level one heading (single #). Note that in strict: false mode the heading numbers might be incorrect between pages and before and after a level 1 heading.

Contributing

Very much open to contributions! Please read CONTRIBUTING.md before putting in any work.

This plugin was inspired by ignorantshr/mkdocs-add-number-plugin, which focuses on enumerating single selected pages.