Skip to content

Add shell block execution with captured output rendering #8

Description

@mwittie

Summary

Add support for executing shell commands from Markdown code blocks during the documentation build and rendering the captured output back into the document.

Problem / Motivation

Documentation examples often show commands that can drift from actual behavior over time. If shell blocks can be executed at build time, the documentation can show verified command output rather than manually copied output.

This helps make documentation a checked, executable artifact rather than static prose.

Proposed Solution

Support an executable shell block syntax and output like:

```bash | litdoc -l text
echo "hello, world"
```

<!--- BEGIN LITDOC OUTPUT -->
```text
hello, world
```
<!--- END LITDOC OUTPUT -->

Acceptance Criteria

  • Shell code blocks can be marked for execution
  • Captured stdout can be rendered into the generated document
  • Captured stderr handling is defined and documented
  • The original command remains visible to readers unless separately suppressed
  • Re-running the build is idempotent and does not duplicate captured output

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions