Hello,
I’ve just published a new tool called markdown-code-runner, a project I’ve been working on over the past few days.
It’s a small CLI utility written in Python that processes Markdown files and looks for fenced code blocks (code enclosed within triple backticks). For each block, it can execute a command based on the declared language and optionally replace the block with the result. It also supports a --check mode to verify that the content of each code block matches the output of the configured command.
This can be useful for:
- keeping documentation examples in sync with reality
- formatting code blocks using tools like
ruff,nixfmt,shfmt, orphp-cs-fixer - running linters or validators on Markdown code snippets
The behaviour is fully configurable via a JSON file. You can define multiple actions per language, choose whether the output should replace the original content, and use placeholders like {file} for more advanced setups.
The project is available here: https://github.com/drupol/markdown-code-runner
Feel free to contribute — this is my very first Python project, so bear with me.
I’ve already tried the tool on the doc/ directory of nixpkgs. The results are promising — you can see the outcome here: https://github.com/NixOS/nixpkgs/pull/397142
For the impatient who wants to try it, it is shipped with a flake, so you can run it with:
nix run github:drupol/markdown-code-runner#markdown-code-runner -- --help
Feedback and suggestions are very welcome. Let me know if you find it useful or if anything’s unclear.
Thanks!
edit: a rewrite in Rust is being written and will be available soon.
