executable documentation smoke tests
Docs should fail like code.
docsmoke runs the Markdown shell and Python examples you mark in README files, install guides, and docs folders, then turns broken snippets into CI failures with precise file and line references.
The problem
Documentation examples rot quietly.
A README command can break after a dependency update, CLI rename, fixture move, or release packaging change. Ordinary tests usually miss that drift because the example lives in prose instead of the test suite.
docsmoke keeps the workflow narrow. It is not a full Markdown linter and not a sandbox. It answers one direct question: do the examples we promised users still run?
The marker
Language first, execution marker second.
In ```bash docsmoke, bash still drives syntax highlighting.
The extra docsmoke token is the opt-in marker that makes the block
executable.
```bash docsmoke # docsmoke: name=hello; expect-contains=hello printf 'hello\n' ```
The workflow
Mark, scan, gate.
pipx install docsmoke docsmoke scan README.md docs examples
GitHub Actions
Use the moving major tag, or pin the exact release.
@v1 is the stable 1.x action line. It moves to the newest compatible
release, so users get fixes. @v1.0.0 is an exact release tag for
workflows that need maximum reproducibility.
- name: Validate executable docs
uses: dev-ugurkontel/docsmoke@v1
with:
paths: README.md docs examples
Version surfaces
There are four names because there are four distribution surfaces.
1.0.0 is the Python package version.v1.0.0 marks the exact release commit and assets.v1 moves to the latest compatible 1.x action release.1, 1.0, 1.0.0, and latest are container image tags.Sample report
Readable locally, structured in automation.
docsmoke passed examples/README.md:5 bash 0.004s ok Summary: total=1 passed=1 failed=0 skipped=0 errors=0
Docs