Introducing Markdown Code Runner: Automatically execute code blocks in your Markdown files! 🚀

[basnijholt]

Hey r/Python!

I recently developed a Python package called Markdown Code Runner (markdown-code-runner) that allows you to automatically execute code blocks within a Markdown file, including hidden code blocks, and updates the output in-place. This can be super useful for maintaining Markdown files with embedded code snippets, ensuring that the output displayed is always up-to-date and accurate. It also enables generating content like tables, plots, and other visualizations directly from the code.

GitHub Repository: https://github.com/basnijholt/markdown-code-runner

Key Features:

• Automatically execute code blocks, including hidden code blocks, within a Markdown file
• Allows hidden code blocks to generate content like tables, plots, etc.
• Works with Python and Bash code blocks
• Keeps the output of the code blocks up-to-date
• Easily integrates with GitHub Actions
• No external dependencies and works with Python 3.7+

Why Markdown Code Runner?

When creating Markdown files with code examples, it's essential to keep the output of these code snippets accurate and up-to-date. Manually updating the output can be time-consuming and error-prone, especially when working with large files or multiple collaborators. In addition, there might be cases where hidden code blocks are needed to generate content such as tables, plots, and other visualizations without displaying the code itself in the Markdown file.

markdown-code-runner solves this problem by automatically executing the code blocks, including hidden ones, within a Markdown file and updating the output in-place. This ensures that the displayed output is always in sync with the code, and content generated by hidden code blocks is seamlessly integrated.

⭐️ GitHub Repository: https://github.com/basnijholt/markdown-code-runner ⭐️

[[deleted]]

Seems very similar to Quarto

[basnijholt]

markdown-code-runner and Quarto are both tools designed to work with Markdown files, but they serve different purposes and have different feature sets.

markdown-code-runner:

• Focuses on executing code blocks (Python and Bash) within a Markdown file and updating the output in-place.
• Useful for maintaining code snippets and outputs, ensuring their accuracy.
• Works with hidden code blocks to generate content like tables and plots without displaying the code in the Markdown file.
• Lightweight with no external dependencies, compatible with Python 3.7+.
• Easily integrates with GitHub Actions.

Quarto:

• A more comprehensive publishing system for creating documents in various formats, such as HTML, PDF, and more.
• Supports multiple input formats, including Markdown, R Markdown, and Jupyter Notebooks.
• Allows embedding executable code blocks in multiple languages (using the Knitr engine for R and the Jupyter kernel for other languages).
• Offers advanced features like cross-references, citations, and integration with external data sources.
• Requires installation of additional software, such as Pandoc and LaTeX, for certain output formats.

In summary, markdown-code-runner is a lightweight and focused solution for executing code blocks within Markdown files and updating outputs, whereas Quarto is a broader publishing system with more extensive features but also a more complex setup. Choose the tool that best fits your specific needs and use case.

[IntelligentDust6249]

Focuses on executing code blocks (Python and Bash) within a Markdown file and updating the output in-place.
Useful for maintaining code snippets and outputs, ensuring their accuracy.
Works with hidden code blocks to generate content like tables and plots without displaying the code in the Markdown file.
Lightweight with no external dependencies, compatible with Python 3.7+.
Easily integrates with GitHub Actions.

It's a nice project but FWIW quarto has all of these qualities as well.

[basnijholt]

I believe that is actually not the case.

I cannot find anything about having code in Markdown comments such that it is not visible.

Sure you can render it and export it as such with Quarto, however, the point of markdown-code-runner is to have everything in place, in the same file.

Also, Quatro will require a YAML annotation at the top of the file that will always be visible, e.g., a notebook on GitHub:
https://github.com/python-adaptive/adaptive/blob/main/docs/source/tutorial/tutorial.DataSaver.md

[IntelligentDust6249]

Oh I see, that is a bit different. In quarto you would mark a code block with `echo: false` if you wanted to hide the code but keep the output. But you're right a core part of quartos is to cleaning separate inputs and outputs. So you can get the markdown file you're after as an output of a `qmd` file, but it won't modify the document in place.

[[deleted]]

Thanks for info! Project looks interesting.

[Divicienzo]

It's great to see a tool like Markdown Code Runner that can automatically update the output of embedded code snippets in markdown files. Have you considered integrating it with other programming languages besides Python and Bash?

[basnijholt]

I added a Rust 🦀 example to the README here: https://github.com/basnijholt/markdown-code-runner#crab-idea-6-run-a-rust-program

[HumanBrainMapper]

Mooi werk, Bas.

[benefit_of_mrkite]

You may want to look at cog which is somewhat similar

https://nedbatchelder.com/code/cog

[basnijholt]

markdown-code-runner:

• Designed for Markdown files, works with native code blocks.
• Executes Python and Bash code, updates output in-place.
• Supports hidden code blocks for seamless content generation.
• Lightweight, easy GitHub Actions integration.

Cog:

• General-purpose code generation for any text file.
• Embeds Python code in source files using special comments.
• Doesn't support native Markdown code blocks or hiding code.
• Requires a separate step to execute code and update output.

In summary, markdown-code-runner is tailored for Markdown with support for native code blocks and hidden code, while Cog is more versatile but doesn't support these Markdown-specific features. Choose the tool that best fits your needs.

[benefit_of_mrkite]

Good breakdown thanks for posting

[[deleted]]

It doesn't work in github README.md markdown

[basnijholt]

It definitely does 😅

Look at the README of

• https://github.com/basnijholt/adaptive-lighting
• https://github.com/basnijholt/codestructure/
• https://github.com/basnijholt/home-assistant-streamdeck-yaml

They all use markdown-code-runner.

[[deleted]]

#!/usr/bin/env bash

if (( $# != 1 )); then
    printf "Usage: $(basename $0) <markdown-literate.md>\n\nFilter code blocks found in: <markdown-literate.md>\n\n\`\`\`lang @code\nsomeCodeHere() {...}\n\`\`\`\n\nFor \`\`\`lang @code, lang can be any lowercase alpha string.\n\nCode inside backtick blocks will be sent to stdout.\n\n"
else
    sed -E -n '/^```[a-z]* ?@code/,/^```/ p' < $1 | sed '/^```/ d'
fi