[kxc42]

Basically you have three approaches to tackle code samples in markdown files:

1. run the code with some kind of plugin as part of your doc pipeline

2. generate documentation from your code

3. take some kind of hybrid approach

I went for 3., annotate snippet "areas" in the source code of a project (mainly in tests) and extract the snippets to a folder, e.g. into the mkdocs folder. I commit them to the (docs) repo. If the project changes, usually I fix the tests and update the snippets in mkdocs. This way I can be sure that the code in the documentation is actually working and people can copy&paste it. To scratch my own itch, I (surprise, surprise) created a script and even packaged it[1].

[1]: https://pypi.org/project/snex/