Configuring/rendering pyodide docs

[Lnk2past]

Is something unclear, missing or outdated in our documentation?

I am very new to this project (and the markdown package, and pyodide in general), so it is likely I missed something pretty important lol. Thanks in advance for the patience and help!

The documentation I think makes some assumptions on how things should be set up, and as a new user I am a little confused. What is the proper way to access/reference the provided pyodide.css and pyodide.js files? What is the proper way to generate standalone pyodide-enabled html?

Relevant code snippets

This is with:

• markdown==3.7
• markdown-exec[ansi]==1.10.0

I initially thought I could just do the following in my script:

from markdown import Markdown
from markdown_exec import formatter, validator

renderer = Markdown(
    extensions=["pymdownx.superfences"],
    extension_configs={
        "pymdownx.superfences": {
            "custom_fences": [
                {
                    "name": "pyodide",
                    "class": "pyodide",
                    "validator": validator,
                    "format": formatter,
                },
            ]
        }
    },
)
text = """
```pyodide
print("Hello World!")
```
"""

with open("test.html", "w") as f:
    f.write(renderer.convert(text))

This populates test.html, but upon opening it in my browser, things were formatted poorly and the code blocks could not be executed. After poking around, I realized that the generated html was referencing some unknown things, and then I realized there are pyodide.css and pyodide.js files that were not being included. So I added the following to the top of my rendered html (referencing my local env):

<script type="text/javascript" src=".venv/lib/python3.12/site-packages/markdown_exec/pyodide.js"></script>
<link rel="stylesheet" href=".venv/lib/python3.12/site-packages/markdown_exec/pyodide.css">

This fixed only some of the formatting issues, the buttons to run/clear seemed reactive now, but not only did the buttons look HUGE, but because I put these files at the top, I got this error in the browser:

pyodide.js:19 Uncaught (in promise) TypeError: Cannot read properties of null (reading 'setStdout')
    at evaluatePython (pyodide.js:19:13)
    at run.onclick (pyodide.js:99:25)

So I moved them down lower in the generated html below the included assets but above the actual Pyodide content. This was now functional, but it seems like I shouldn't need to manually inject the internal .css and .js, so it very much seems like I am missing something important either in my configuration, or my usage. I can manually modify the generated HTML to fix the button sizes, but that seems awfully unnecessary.

Screenshot

Link to the relevant documentation section

• https://pawamoy.github.io/markdown-exec/
• https://pawamoy.github.io/markdown-exec/usage/pyodide/

[pawamoy]

Hello @Lnk2past, thanks for opening an issue 🙂

You are completely right, the docs aren't clear at all. The missing information is that the asset files are automatically included when using the MkDocs plugin, while they must be added manually when using the Markdown (SuperFences really) extension directly. The docs should definitely explain that, sorry for the trouble!

I'd also be open to a feature request to automatically add these assets even when not using the MkDocs plugin.

[Lnk2past]

Hey @pawamoy thanks for the reply! And no worries - it was a good learning experience!

I don't have a ton of time, but I don't mind trying to squeeze some time in to submit a PR to the docs if you're ok with that. Beyond that I can also take a stab at such a feature request, but I'll need to familiarize myself with the code here a bit. There is definitely no urgency on my end, so no problem either way!

[pawamoy]

A docs PR would be awesome! Note I said you could open a feature request for the asset thing, you don't have to send a PR for it 😄