Metadata-Version: 2.4
Name: mkdocs-nav-numbering-plugin
Version: 1.2.0
Summary: MkDocs plugin to add hierarchical numbering to nav and page headings
Author: Matus Drobuliak
License: MIT
Project-URL: Homepage, https://github.com/matusdrobuliak66/mkdocs-nav-numbering-plugin
Project-URL: Repository, https://github.com/matusdrobuliak66/mkdocs-nav-numbering-plugin
Project-URL: Issues, https://github.com/matusdrobuliak66/mkdocs-nav-numbering-plugin/issues
Keywords: mkdocs,plugin,navigation,numbering,documentation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs>=1.4
Dynamic: license-file

# mkdocs-nav-numbering-plugin

[![CI](https://github.com/matusdrobuliak66/mkdocs-nav-numbering-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/matusdrobuliak66/mkdocs-nav-numbering-plugin/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mkdocs-nav-numbering-plugin.svg)](https://pypi.org/project/mkdocs-nav-numbering-plugin/)

MkDocs plugin that adds hierarchical numbering to navigation items and page headings.

## Features

- Number nav sections, pages, and links (optional)
- Number page headings based on nav position
- Configurable depth limits for nav and headings
- Configurable separator
- Exclude specific pages

![image](resources/image.png)

## Installation

```bash
pip install mkdocs-nav-numbering-plugin
```

## Usage

```yaml
plugins:
  - nav-numbering:
      nav_depth: 4
      heading_depth: 5
      number_h1: true
      number_nav: true
      number_headings: true
      preserve_anchor_ids: false
      separator: "."
      exclude:
        - index.md

markdown_extensions:
  - attr_list  # Required when preserve_anchor_ids is true
```

## Options

- `enabled` (bool, default: true)
- `nav_depth` (int, default: 0) — 0 means unlimited
- `heading_depth` (int, default: 0) — 0 means unlimited
- `number_nav` (bool, default: true)
- `number_headings` (bool, default: true)
- `number_h1` (bool, default: true)
- `preserve_anchor_ids` (bool, default: false) — Preserve original heading anchor IDs without number prefixes (requires `attr_list`)
- `separator` (str, default: ".")
- `exclude` (list, default: [])

### `preserve_anchor_ids`

By default, MkDocs generates heading IDs from the final heading text. Since this plugin prepends numbering, your anchors can end up including the numbers.

Enable `preserve_anchor_ids: true` to add explicit `{#...}` IDs based on the original (un-numbered) heading text. Duplicate headings are automatically suffixed with `-1`, `-2`, etc.

```yaml
plugins:
  - nav-numbering:
      preserve_anchor_ids: true

markdown_extensions:
  - attr_list
```
