How Rundoc Embeds Command Output into Markdown

Rundoc for Pandoc: Automate Code Execution in Documents

What it is
Rundoc for Pandoc is a workflow/tooling pattern that runs code blocks while converting documents with Pandoc, capturing their output (text, command results, images) and embedding that output into the generated document so the final file contains live, reproducible results.

Key features

• Automatic code execution: Runs specified code blocks during Pandoc conversion.
• Output capture: Inserts stdout, stderr, exit codes, or generated files (images, CSV) into the document.
• Language-agnostic: Can execute shell commands or language-specific scripts (Python, R, Bash) via configured runners.
• Declarative control: Mark code blocks with attributes (e.g., run=true, capture=all, fig=true) to control execution and embedding.
• Reproducibility: Keeps source code and outputs synchronized; useful for reproducible reports and technical docs.

Typical workflow

1. Write a Markdown (or other Pandoc-supported) document with fenced code blocks.
2. Add attributes to blocks indicating they should be executed (e.g., bash {rundoc=true}).
3. Run Pandoc with a filter or preprocessor (a rundoc plugin/script) that:
   • Extracts executable blocks,
   • Executes them in an isolated environment,
   • Captures outputs and generated files,
   • Rewrites the document AST to include results (inline output, image references).
4. Produce the final format (HTML, PDF, DOCX) with outputs embedded.

Common use cases

• Data analysis reports where charts/tables are generated from live code.
• Technical documentation showing actual command outputs or CLI examples.
• Tutorials and notebooks converted to traditional docs with runnable examples.
• CI pipelines that regenerate docs from canonical source code before release.

Example code-block annotation (Markdown)

markdown
Copy CodeCopied
”`bash {rundoc=true, capture=“stdout”} echo “Version: $(python –version 2>&1)” 

Code
Copy CodeCopied
(After processing, the document will include the echoed line under the code block.) 

 
Benefits
 

Ensures documentation reflects current code behavior.
Reduces manual copy-paste of outputs.
Simplifies maintenance of examples and reproducible artifacts.### Caveats and best practices
Security: Executing code during build is risky—avoid running untrusted code and use sandboxing/CI isolation.
Determinism: Ensure scripts are deterministic (pin dependencies, set seeds) to avoid noisy diffs.
Performance: Long-running or resource-heavy blocks can slow builds; mark them to skip in quick builds if needed.
Caching: Use output caching to avoid re-running expensive steps every build.

 
Tools & integration
 

Implementations typically come as Pandoc filters or preprocessors (Lua filters, external scripts).
Integrate with CI (GitHub Actions, GitLab CI) to regenerate outputs automatically.
Can be combined with literate programming tools and static site generators that use Pandoc.

 
If you want, I can:
 

Show a concrete Pandoc Lua-filter example that executes shell blocks and embeds stdout.
Draft a small CI workflow to run rundoc during site builds. Which would you prefer?