feat: add NumberedHeadingsPreprocessor

[sapristi]

Fixes #1586

Add pre-processor that adds numbering to markdown headers:

transforms title in markdown cells, such that e.g.

# title 
## subtitle
content 
# other title

turns into

# 1 title 
## 1.1 subtitle
content 
# 2 other title

[krassowski]

Thank you @sapristi for sending the PR. Was this requested in an issue before? Just trying to understand if there is sufficient community need for this to live in nbconvert given the maintenance costs for adding a new pre-processor.

[sapristi]

Hello, I just checked, it seems that some people were interested in this as well, e.g. #1586

IMO this is a very essential feature for working with a document - it's also a feature provided in the Jupyter web UI, so I think I'm not the only one.

[krassowski]

What if I we have a code in markdown, e.g.:

This is how you create a heading in Markdown
```markdown
# heading
```

It feels like a more robust solution would be to use mistune API for parsing, see https://mistune.lepture.com/en/latest/api.html (markdown_mistune is already in use here, but it should fail nicely).

It is also possible to instruct pandoc to run with --number-sections (see https://www.youtube.com/watch?v=gDV63UMJR_U and https://pandoc.org/chunkedhtml-demo/8.3-headings.html and https://pandoc.org/MANUAL.html) but pandoc is neither the only nor even default markdown parser.

[sapristi]

Hello,
sorry for the late reply, I'm a bit busy at the moment.

Indeed, I'll make that more robust with mistune parsing / treatment / dumping back to markdown.

About your pandoc remark, I'm not sure to follow you.

[sapristi]

Implemented changes to use mistune for parsing

• only compatible with mistune v3, do you think it's worth it keeping compatibility with v2 as well ?
• I'm using a logger, not sure if that's the preferred way to report warning / errors to users ?

[krassowski]

only compatible with mistune v3, do you think it's worth it keeping compatibility with v2 as well ?

I think that's fine

I'm using a logger, not sure if that's the preferred way to report warning / errors to users ?

I left a comment on the code

[sapristi]

Just added the processor here, otherwise it was not running python -m nbconvert --to=html --NumberedHeadingsPreprocessor.enabled=true notebook.ipynb (even though the option to enable it appeared in python -m nbconvert --help-all

[paolovic]

nice work, thank you @sapristi !