Keep documentation current by expanding code blocks in plain Markdown
A minimal Golang tool that injects command output directly into your docs, avoiding heavy notebook formats.
- LinkLoot access
- Free
- Provider costs
- Unknown
What you get from it
What it does
docexp is a lightweight utility designed to expand code blocks within standard Markdown files. Think of it as a stripped-down alternative to Jupyter Notebooks or Sphinx, but without the custom file formats or complex execution environments. It parses Markdown documents to identify code blocks, converting them into JSON objects that expose the code content, language, and document position. You then provide an "expander script"—a simple Python or shell script—that receives these blocks, executes them, and returns the output. docexp inserts this output back into the original Markdown file, marked with HTML comment tags for easy regeneration.
Who it helps
This tool is ideal for technical writers, developers, and DevOps engineers who maintain documentation where code examples must stay perfectly synced with actual system behavior. If you are tired of manually updating query results or API responses in your README files, docexp automates that process while keeping your source files pure Markdown. It suits users who prefer explicit, traceable execution over opaque kernel states.
Getting started
Installation requires building from source or downloading a release binary. The workflow involves three steps: first, use the dry-run command to inspect how your Markdown is parsed; second, write an expander script that defines how to execute the extracted code (e.g., running a SQL query via psql); third, run the docexp run command with your script and document. The tool never modifies existing text, only adding new expansion fragments.
Limits and costs
Currently in BETA (v0.1.*), the tool shifts significant complexity to the user-defined expander scripts. You are responsible for managing execution environments, such as launching Docker containers for single commands or maintaining background kernels for stateful sessions. Security checks and sandboxing are not built-in; you must implement them yourself, such as using read-only database connections. While the software is open-source under GPL-3.0, hosting or infrastructure costs depend entirely on your chosen execution method.
Source links
Discussion
Share practical experience, questions, or warnings with the community.
Sign in to join the discussion and vote on comments.
Sign in