markdown-heading-numbering
CLI formatter and pre-commit hook that adds hierarchical numbering to Markdown headings.
Table of Contents
- 1. Why add numbering to markdown headings?
- 2. How to use this tool?
- 3. Compatibility with other formatters
1. Why add numbering to markdown headings?
Here are some benefits of numbering markdown headings:
- Improve readability
- Numbering naturally indicate hierarchy: "3.1.6" is the child of "3.1"
- Without numbering, we'd rely on font style & size to tell hierarchy, which is not reliable
- Reduce communication overhead in a team setting
- You can reference the section by "Section 2.3.5" instead of "the section named 'Monthly Sales Trend and What That Means for Our Business in the Long Run'"
- Make diffs clearer
- Renumbered headings reveal structural edits instead of hiding content changes in walls of text
2. How to use this tool?
2.1. As a command-line tool
First, install it from PyPI:
pip install markdown-heading-numbering
And then:
markdown-heading-numbering \
--start-from-level 2 \
--end-at-level 5 \
--initial-numbering 1 \
docs/README.md
Options:
--start-from-level(int, default2): first heading level to number.--end-at-level(int, default6): last heading level to number (inclusive).--initial-numbering(int, default1): starting value for the top-most numbered heading.
Any existing numbering is removed before the formatter applies the new sequence.
2.2. As a pre-commit hook
This repository ships a .pre-commit-hooks.yaml that points to the CLI. Add
the hook to your .pre-commit-config.yaml:
- repo: https://github.com/jsh9/markdown-heading-numbering
rev: <commit-or-tag>
hooks:
- id: markdown-heading-numbering
args:
- --start-from-level=2
- --end-at-level=4
- --initial-numbering=1
The hook shares the same options as the CLI and formats files in place.
3. Compatibility with other formatters
3.1. With markdown-toc-creator
If you are also using my other markdown formatter
markdown-toc-creator as a
pre-commit hook to for create tables of contents in your markdown files, put
that hook after this one.
3.2. With mdformat
This tool is fully compatible with
mdformat as pre-commit hooks.
Metadata
Release files for markdown-heading-numbering 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| markdown_heading_numbering-0.1.1.tar.gz | 6.6 kB | Without provenance | Details for markdown_heading_numbering-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| markdown_heading_numbering-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for markdown_heading_numbering-0.1.1-py3-none-any.whl |
Total release size: 13.6 kB
Release files / markdown_heading_numbering-0.1.1.tar.gz
| Download URL | markdown_heading_numbering-0.1.1.tar.gz |
|---|---|
| Size | 6.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c2d20391868506b6c17968c4b132017e8daf8f27725ed954f0c193d845243044
|
|
BLAKE2b-256 checksum How to use checksums |
2d21e52d312ad944382fd2e3500153e9d07269da15245e7d62cc3be27b427034
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / markdown_heading_numbering-0.1.1-py3-none-any.whl
| Download URL | markdown_heading_numbering-0.1.1-py3-none-any.whl |
|---|---|
| Size | 7.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fc7824448d2a65894498f4d4473f34ebd491d5f78f500a4da9ffeeb5bad881f3
|
|
BLAKE2b-256 checksum How to use checksums |
dcb7b467929e8ce534026180c79a28077b1a8bc4c9021ed7446c489e5e01f1c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for markdown-heading-numbering 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.