Package: mkdocs-enumerate-headings-plugin
mkdocs-enumerate-headings-pluginMkDocsPlugin to enumerate the headings (h1-h6) across MkDocs pages.:point_right: If you're looking to add heading numbers to your site to support exporting to single-page standalone HTML or a PDF file, have a look atmkdocs-print-site-plugininstead!Features :star2:Automatically number all headings and (optionally) give each page an sequential chapter numberGreat for writing (technical) reportsCompatible withpluginslikeawesome-pagesandmonorepoCompatible withmarkdown_extensionslikepymdownx.snippetsCompatible with themes likemkdocs-materialEasy to customize styling through CSSSetupInstall the plugin usingpip:pip3installmkdocs-enumerate-headings-pluginNext, add the following lines to yourmkdocs.yml:plugins:
  - search
  - enumerate-headingsMkDocs executes plugins in the order they are defined. If you use any other plugins that alter the navigation, make sure to define thembeforetheenumerate-headingsplugin.If you have nopluginsentry in your config file yet, you'll likely also want to add thesearchplugin. MkDocs enables it by default if there is nopluginsentry set.Usageenumerate-headingswill increment the chapter number for each new page (in the order they appear in the navigation) and enumerate all subheadings (unless you disable in this in the options).There is only one requirement: make sure each markdown page starts with a level 1 header (seehow to write markdown headers). Some MkDocs themes will handle this for your automatically, inserting the page title as a heading 1 if you do not specify one. If a heading 1 is still missing, you'll get a helpful error.Pages with multiple level 1 headings are allowed and the chapter numbers will increment accordingly.Note this plugin does not affect your markdown files, only the rendered HTML.StylingAll heading numbers are wrapped in<span class='enumerate-headings-plugins'></span>and can be styled using CSS. Seecustomizing a MkDocs themeon how to add an CSS to your theme.As an example you can make the numbering lighter than the heading title by saving the CSS snippet below to a file and adding it to your MkDocs site using theextra_csssetting in yourmkdocs.ymlfile./* Extra CSS for mkdocs-enumerate-headings-plugin */.enumerate-headings-plugin{filter:opacity(35%);}OptionsYou can customize the plugin by setting options inmkdocs.yml:plugins:
    - enumerate-headings:
        toc_depth: 0
        strict: true
        increment_across_pages: true
        include:
          - "*"
        exclude:
          - index.md
          - another_page.md
        restart_increment_after:
          - second_section.mdtoc_depth(default0): Up to which level the table of contents should be enumerated as well. Default is 0, which means the TOC is not enumerated at all. Max is 6 (showing all enumeration)strict(defaulttrue): Raise errors instead of warnings when first heading on a page is not a level one heading (single#) and your MkDocs theme has not inserted the page title as a heading 1 for you. Note that instrict: falsemode the heading numbers might be incorrect between pages and before and after a level 1 heading.increment_across_pages(defaulttrue): Increment the chapter number for each new page (in the order they appear in the navigation). If disabled, each page will start from 1.include(default["*"]): Specify a list of page source paths (one per line) that should have enumeration (included in processing by this plugin). This can be useful for example to include enumeration on only one directory. The source path of a page is relative to yourdocs/folder. You can also useglobsinstead of source paths. For example, to includedocs/subfolder/page.mdspecify in yourmkdocs.ymla line underinclude:with- subfolder/page.mdexclude(defaultnot specified): Specify a list of page source paths (one per line) that should not have enumeration (excluded from processing by this plugin). This can be useful for example to remove enumeration from the front page. The source path of a page is relative to yourdocs/folder. You can also useglobsinstead of source paths. For example, to excludedocs/subfolder/page.mdspecify in yourmkdocs.ymla line underexclude:with- subfolder/page.mdrestart_increment_after(defaultnot specified): Specify a list of page source paths (one per line) where enumeration should be restarted. This can be useful if you have multiple reports or tutorials in one mkdocs site. Paths behave as withexclude(can use globs).ContributingContributions are very welcome! Please readCONTRIBUTING.mdbefore putting in any work.Credits: This plugin was inspired byignorantshr/mkdocs-add-number-plugin, which focuses on enumerating single selected pages.