9.6.15 mkdocs build assertion error

[alechartung]

Context

Hitting an assertion error after upgrading to 9.6.15.

Seems to be an issue when a markdown file contains this string: `<>...</>`

Log:

$ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/alec/code/mkdocs-repro/site
ERROR   -  Error reading page 'index.md': we should not get here!
Traceback (most recent call last):
  File "/home/alec/code/mkdocs-repro/.venv/bin/mkdocs", line 10, in <module>
    sys.exit(cli())
             ^^^^^
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/click/core.py", line 1442, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/click/core.py", line 1363, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/click/core.py", line 1830, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/click/core.py", line 1226, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/click/core.py", line 794, in invoke
    return callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/mkdocs/__main__.py", line 288, in build_command
    build.build(cfg, dirty=not clean)
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/mkdocs/commands/build.py", line 310, in build
    _populate_page(file.page, config, files, dirty)
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/mkdocs/commands/build.py", line 167, in _populate_page
    page.render(config, files)
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/mkdocs/structure/pages.py", line 285, in render
    self.content = md.convert(self.markdown)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/markdown/core.py", line 354, in convert
    self.lines = prep.run(self.lines)
                 ^^^^^^^^^^^^^^^^^^^^
  File "/home/alec/code/mkdocs-repro/.venv/lib/python3.12/site-packages/mkdocs/structure/pages.py", line 529, in run
    parser.feed('\n'.join(lines))
  File "/usr/lib/python3.12/html/parser.py", line 111, in feed
    self.goahead(0)
  File "/usr/lib/python3.12/html/parser.py", line 171, in goahead
    k = self.parse_starttag(i)
        ^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/html/parser.py", line 303, in parse_starttag
    endpos = self.check_for_whole_start_tag(i)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/html/parser.py", line 376, in check_for_whole_start_tag
    raise AssertionError("we should not get here!")
AssertionError: we should not get here!

Bug description

After upgrading to 9.6.15, our document build hits an assertion.
Downgrading to 9.6.14 fixes.

Related links

• Reporting a bug

Reproduction

9.6.15-better-repro.zip

Steps to reproduce

1. download + extract reproduction
2. uv venv .venv
3. uv pip install -r requirements.lock.txt
4. remove info plugin
5. uv run 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 using the built-in info plugin.

[squidfunk]

Thanks for reporting. That's odd. It looks like it doesn't have to do with us, since no line of code of Material for MkDocs appears in the stack trace. Also, there's an issue with the same problem already reported on MkDocs, see mkdocs/mkdocs#4001

Not sure what to do here. Can you verify that you only upgraded Material for MkDocs, and no other dependency?

[alechartung]

We run our documentation build through Dagger, like this:

  /**
   * Docs: Run mkdocs build
   */
  @func()
  async docsBuild(): Promise<number> {
    return dag
      .container()
      .from("squidfunk/mkdocs-material:9.6.14")
      .withExec([
        "pip",
        "install",
        "--no-cache-dir",
        "mkdocs-literate-nav",
        "mkdocs-swagger-ui-tag",
        "mkdocs-mermaid2-plugin",
      ])
      .withWorkdir("/app")
      .withDirectory("/app/docs", this.docsSource)
      .withFile("/app/mkdocs.yml", this.mkdocsSource)
      .withExec(["mkdocs", "build", "--strict"])
      .exitCode();
  }

The error happens with squidfunk/mkdocs-material:9.6.15 but not when we downgrade to squidfunk/mkdocs-material:9.6.14. It could be that squidfunk/mkdocs-material:9.6.15 is using a newer mkdocs version?

[squidfunk]

Ah, you're using Docker, that wasn't mentioned in the issue. Here are the Docker builds:

9.6.14 – Docker build

#13 28.76 Successfully installed MarkupSafe-3.0.2 babel-2.17.0 backrefs-5.8 certifi-2025.4.26 charset-normalizer-3.4.2 click-8.2.0 colorama-0.4.6 ghp-import-2.1.0 idna-3.10 jinja2-3.1.6 markdown-3.8 mergedeep-1.3.4 mkdocs-1.6.1 mkdocs-get-deps-0.2.0 mkdocs-material-9.6.14 mkdocs-material-extensions-1.3.1 packaging-25.0 paginate-0.5.7 pathspec-0.12.1 platformdirs-4.3.8 pygments-2.19.1 pymdown-extensions-10.15 python-dateutil-2.9.0.post0 pyyaml-6.0.2 pyyaml-env-tag-1.0 requests-2.32.3 six-1.17.0 urllib3-2.4.0 watchdog-6.0.0

9.6.15 – Docker build

#13 27.09 Successfully installed MarkupSafe-3.0.2 babel-2.17.0 backrefs-5.9 certifi-2025.6.15 charset_normalizer-3.4.2 click-8.2.1 colorama-0.4.6 ghp-import-2.1.0 idna-3.10 jinja2-3.1.6 markdown-3.8.2 mergedeep-1.3.4 mkdocs-1.6.1 mkdocs-get-deps-0.2.0 mkdocs-material-9.6.15 mkdocs-material-extensions-1.3.1 packaging-25.0 paginate-0.5.7 pathspec-0.12.1 platformdirs-4.3.8 pygments-2.19.2 pymdown-extensions-10.16 python-dateutil-2.9.0.post0 pyyaml-6.0.2 pyyaml-env-tag-1.1 requests-2.32.4 six-1.17.0 urllib3-2.5.0 watchdog-6.0.0

Updates

Here are the libraries that received updates:

1. backrefs: 5.8 → 5.9
2. certifi: 2025.4.26 → 2025.6.15
3. click: 8.2.0 → 8.2.1
4. markdown: 3.8 → 3.8.2
5. pygments: 2.19.1 → 2.19.2
6. pymdown-extensions: 10.15 → 10.16
7. pyyaml-env-tag: 1.0 → 1.1
8. requests: 2.32.3 → 2.32.4
9. urllib3: 2.4.0 → 2.5.0

I'm quite confident that none of the updates except for markdown and pymdown-extensions would have anything to do with this, but of course you can never rule it out. Regardless, since Markdown is part of the stack trace you posted, it's the first thing to look into. Does downgrading Markdown to 3.8 resolve the issue? The last releases, i.e., 3.8.1 and 3.8.2 look like they could include changes that might be relevant: https://github.com/Python-Markdown/markdown/releases

Please try to downgrade the dependencies, and if you happen to find the one that's causing the issue, please let us know.

[squidfunk]

I'd guess that this commit might have introduced the regression:
Python-Markdown/markdown@64a3c0f

CC @facelessuser for visibility.

[facelessuser]

I'd guess that this commit might have introduced the regression:
Python-Markdown/markdown@64a3c0f

@squidfunk This is not a Markdown bug, but the issue is related to the change. Prior to the fix, </> would just disappear due to how the Python HTML parser handled the content.

This is the latest Markdown, there is no issue when it comes to parsing.

import markdown

print('Markdown Version:', markdown.__version__)
print('========')

text = """
`<>...</>`
"""

html = markdown.markdown(text)
print(HTML)

$ python3 example.py
Markdown Version: 3.8.2
========
<p><code>&lt;&gt;...&lt;/&gt;</code></p>

So what is going wrong?

MkDocs seems to have created its own preprocessor that they expose via a markdown plugin, and they've included their own HTML handler that inherits from Markdown's parser to try and intercept things from it. Unfortunately, this can be fragile if something changes, and they do not account for it. They need to update their logic to be compatible with recent changes.

[facelessuser]

I've created a PR over on MkDocs that adds the missing logic and should fix this issue moving forward, as long as they merge it and release it: mkdocs/mkdocs#4007.

[squidfunk]

Thanks for the quick fix! What should we do until the PR is merged? The last PRs that were merged (not closed) were:

• Update CI badge mkdocs/mkdocs#3933 (Feb 12, 2025 – no code)
• fix and test description of draft_docs mkdocs/mkdocs#3859 (Nov 6, 2024 – no code, only docs and tests)
• Version 1.6.1. mkdocs/mkdocs#3819 (Aug 30, 2024 – MkDocs 1.6.1 release notes)

Should we pin Markdown to 3.8 in the meantime until the upstream fix is released, so at least it doesn't crash? IIUC, this will result in </> being stripped, but at least it does not crash the build without a useful error message.

[facelessuser]

Should we pin Markdown to 3.8 in the meantime until the upstream fix is released, so at least it doesn't crash? IIUC, this will result in </> being stripped, but at least it does not crash the build without a useful error message.

That is certainly an approach that could be taken. Some pressure should be put on the MkDocs team as well to get the bugfix released as well. Having content mysteriously disappear is not great either and will often go unnoticed by authors, but is probably the lesser evil.

The built-in HTML parser in Python only cares about HTML. The Markdown altered parser is trying to parse HTML, but preserve invalid HTML that may be in code blocks or used in prose and not in the context of HTML.

I'm going to have to check MkDocs against Python 3.14 soon as Python changed some more things about their HTML parser that Markdown had to account for and likely MkDocs is not.