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. generat

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/ https://pypi.org/project/snex/