pawamoy / pawamoy/markdown-exec
bug: IndexError when an exec block shares a page with a large `:::` mkdocstrings directive
@pawamoy is already working on this.
Since May 20, 2026.
- Dominant language
- Python
- Stars
- 174
- Forks
- 21
- PR merge metrics
- No merged PRs in 30d
Description
Hi!
I ran into a build failure I'm fairly sure comes from markdown-exec.
I have a reference page with one python exec="true" block near the top
and :::tsecon.x13._spec lower down. The submodule documents about 87 symbols.
With both on the same page, mkdocs build dies with:
File ".../markdown_exec/_internal/processors.py", line 105, in run
markup: Markup = self.md.htmlStash.rawHtmlBlocks[counter]
IndexError: list index out of range
Either one alone is fine. It only breaks in combination.
I spent a while bisecting and the failure seems to track the number of
stashed HTML blocks mkdocstrings emits, not anything specific in any one
docstring (spot-removing individual docstrings doesn't help; the failure
just shifts around). Threshold seems to be somewhere around 80 stashed
blocks.
Bisection, all with the same exec block on the page:
::: target |
symbols | result |
|---|---|---|
| ._x13 | 4 | ok |
| ._result.run | 1 | ok |
| ._result | 15 | ok |
| ._spec.series | 1 | ok |
| ._spec | ~87 | crash |
Smallest repro I have:
# Title
```python exec="true" source="material-block"
print("hi")
```
::: package_with_many_symbols
For now I dropped exec="true" on that one page and shipped the
quick-start as plain python; the rest of the docs build fine. I'm just
reporting this so it's on your radar. I would be happy to put together
a stripped-down reproducer if that would help.
(markdown-exec 1.12.1, mkdocstrings python handler current, mkdocs-material current.)
Thanks for markdown-exec, by the way, we use it across our whole
tutorial corpus.
Best!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.