Run your code samples. Surface the real bugs.
DocsAlive is a docs CI. It treats every example in your documentation as a test, runs it against the version you ship, and tells you exactly which ones a customer would trip over.
4 likely docs bugs in Project A
204 code blocks across 24 pages, run against the current release.
TypeError: get() got an unexpected keyword argument 'extensions'Everything else that failed was triaged as not a docs bug (missing context, needs credentials, network) and left out of the check.
Top-level get() no longer accepts extensions=
extensions.md:156 · api-drift · likely docs bug
As documented
extensions = {"target": b"/test^path"} response = lib.get("https://www.example.com", extensions=extensions)
Sandbox output
$ python snippet.py # current release, python 3.12 Traceback (most recent call last): File "<docs-snippet>", line 13, in <module> TypeError: get() got an unexpected keyword argument 'extensions'
Why this is classified as a docs bug
The call fails on a keyword the current API rejects (api-drift), not on missing context, credentials or network. A reader who copies this example gets an error. Pattern: TypeError: … unexpected keyword argument → api-drift, docs bug.
extensions through a ClientVerification (re-run in the sandbox)
TypeError: get() got an unexpected keyword argument 'extensions'Fix PRs open as drafts. Nothing merges without a maintainer's approval. For this demo our team wrote the fix and the engine verified it.
Real output from DocsAlive v0.2.1 on a popular open-source Python HTTP client, run October 19, 2026. Project, package and path names are redacted until we have reported the findings to the maintainers. The Check, Finding and CLI views are unedited engine output. The Fix PR view shows a fix our team wrote and the engine verified. It has not been submitted upstream.
Executes, not just lints
A linter can tell you a snippet parses. Only running it tells you the API still behaves the way the page says. DocsAlive runs each block the way a reader would, in page order, with the page's own install steps.
- Python scripts and interactive
>>>sessions, with documented output compared to real output - JavaScript (CommonJS and ESM, top-level
await) and simple TypeScript - Shell and console blocks, with
$prompts and output lines told apart curlcommands and raw HTTP request blocks- JSON and TOML validated. Configuration fragments are syntax-checked, not executed
| Outcome | Blocks |
|---|---|
| Passed as written | 65 |
| Ran, output differs | 10 |
| Failed (all reasons) | 111 |
| Skipped with a reason | 18 |
| Likely docs bugs | 4 |
How 204 blocks became 4 findings
Project A, every category except passing blocks
| Category | Blocks | Docs bug? |
|---|---|---|
| depends-on-context | 70 | no |
| runtime-error | 17 | review |
| missing-install-step | 10 | no |
| output-block | 10 | no |
| output-differs | 9 | no |
| missing-fixture | 5 | no |
| network-external | 5 | review |
| not-executable | 3 | no |
| fragment | 3 | no |
| api-drift | 2 | yes |
| needs-credentials | 2 | no |
| invalid-syntax | 1 | yes |
| stale-output | 1 | yes |
| timeout | 1 | review |
Triage that filters noise
Most docs snippets aren't meant to run on their own. They reference a variable from three paragraphs up, need an API key, or call a live service. Reporting all of that as "broken" is how docs tests get switched off.
DocsAlive puts every result into one of 24 categories and only escalates the ones a reader would actually hit: removed imports, renamed parameters, invalid syntax and outdated output. On our small hand-labeled sample (40 findings, 7 real bugs), precision is 100.0%. Results on your docs may differ.
Fixes as draft pull requests
For each real docs bug, DocsAlive proposes the smallest change that makes the example work again. It re-runs the fixed example in the sandbox and opens a draft PR with the evidence attached.
- Before/after sandbox output in the PR description
- One PR per page, so each change is easy to review
- Designed not to merge. A maintainer reviews and merges every change
- Bring your own model provider, or turn fix drafting off entirely
SyntaxError: invalid syntax. Perhaps you forgot a comma?Real finding on Project A (names redacted). Fix shown for illustration and not yet submitted upstream.
Fits where your docs already live.
OpenAPI checks
Finds OpenAPI specs in your repo and checks every $ref resolves. On Project B: 68 operations, 87 examples, 0 broken references.
GitHub checks
A check run on each pull request with line-level annotations. It is set to neutral when failures aren't docs bugs, so noise alone shouldn't block a merge.
Release & nightly runs
Re-test docs when you tag a release, and nightly to catch drift in the third-party packages your examples install.
Docs health badge
An SVG badge for your README or docs site that shows passing or failing for the latest run.
Framework-aware
Understands MkDocs, Mintlify, Docusaurus, ReadMe exports and plain Markdown/MDX, including tabbed code groups.
Portable reports
Every run produces a Markdown summary and a JSON report you can archive, diff or feed into your own tooling.
See it on your own docs.
The free Docs Health Check runs the same engine on a public repository.