Repository navigation
Provide a CI example for validating runnable Markdown snippets #12
Description
Activity
This was generated by AI during triage.
Agent Brief
Category: enhancement
Summary: Provide a copyable CI recipe for extracting intentionally runnable snippets into an isolated workspace and validating them.Current behavior:
The run command writes one temporary file per block and invokes a caller-provided shell command, but it does not supply a reusable extracted-workspace CI example. No public metadata convention identifies which Markdown snippets are intended to be runnable.Desired behavior:
Consumers can mark intentionally runnable code fences with runnable=true, extract only those fences into a newly created isolated workspace, and invoke a trusted, configurable validation command against that workspace. Validation failures fail CI and identify the affected snippets or generated files. Temporary output is reliably cleaned up.Key interfaces:
- Runnable metadata convention — runnable=true selects only code blocks intended for execution or validation.
- Isolated workspace — create a fresh temporary output directory outside source files, extract selected blocks there, and clean it up on success or failure.
- Validation command — accept a consumer-supplied command as trusted CI configuration; Markdown metadata must not provide a command to run.
- Diagnostics — report generated file paths and validation failures so a consumer can trace failures back to the source Markdown blocks.
- CI examples — provide local-shell and GitHub Actions recipes that can be adapted to language-specific lint or test commands.
Acceptance criteria:
- A documented example selects only runnable=true blocks.
- It extracts selected blocks into a newly created isolated workspace.
- It runs a configurable, trusted validation command against the extracted files.
- Validation failures return a non-zero status and identify the failing generated file or block.
- The temporary workspace is cleaned up safely after success and failure.
- Documentation explains the runnable=true convention and trust boundary.
- Tests cover selection, successful validation, validation failure, and cleanup.
Out of scope:
- Treating all code fences as independently runnable by default.
- Type-checking arbitrary snippets or providing editor diagnostics.
- Executing a command specified by Markdown metadata.
- Release gating, which is issue Gate package releases on mdcode documentation and example checks #13.
Verification status:
Confirmed: current run behavior is per-block and console-oriented; no extracted-workspace CI example or runnable metadata convention exists. This issue is blocked by #7.- added a commit that references this issue
on Oct 4, 2026
Parent
#10
What to build
Provide a CI-ready example for extracting selected Markdown code blocks and validating them as runnable examples. Consumers should be able to adapt it to the language-specific test or lint command used by their project.
Acceptance criteria
Blocked by