typeset plugin reads headings in code blocks

[pawamoy]

Context

I'm writing some docs for mkdocstrings where we show how you can inject documentation for an object directly in a heading line:

## ::: path.to.object

Bug description

The typeset plugin naively picks up Markdown lines starting with # without checking if they're part of a fenced code block. It then converts those lines using the extension configured in mkdocs.yml, in this case mkdocstrings, which triggers all the code scanning + HTML rendering machinery, causing issues.

Related links

https://github.com/squidfunk/mkdocs-material-insiders/blob/d82bb8e0a5ef39bed97e6a8849b8146dfd7afbb1/material/plugins/typeset/plugin.py#L74-L77

Reproduction

example.zip

Steps to reproduce

cd repro-typeset
python -m venv .venv
. .venv/bin/activate
python -m pip install mkdocs-material mkdocstrings[python]
mkdocs build

Browser

No response

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues and discussions.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction.

[pawamoy]

Here's a suggestion (probably naive as well):

headings = []
in_code_block = False
for line in page.markdown.split("\n"):
    if line.startswith("```"):
        if in_code_block:
            end_ticks = len(line) - len(line.lstrip("`"))
            if end_ticks == start_ticks:
                in_code_block = False
        else:
            start_ticks = len(line) - len(line.lstrip("`"))
            in_code_block = True
    elif line.startswith("#") and not in_code_block:
        headings.append(line)

html = self.markdown.convert("\n".join(headings))

[squidfunk]

Thanks for reporting and providing a possible solution! The reported problem should be fixed in 86264095f. I've switched the current approach that does Markdown parsing to use two regexes to remove the anchor links from the headlines (which would otherwise result in nested anchors = invalid HTML). Can you confirm that the issue is gone?

[pawamoy]

Ah, that's great! Some extensions/plugins generate headings and these would not have been caught by the previous version of the code. Working on HTML allows to pick up every headings, static or generated 👍 I'll try the fix and report back 🙂 Thanks!

[squidfunk]

The issue is resolved, as discussed on Gitter with @pawamoy.

[squidfunk]

Released as part of 9.1.12-insiders-4.34.0.