Getting started

Run your first scan, read the results, and connect a repository.

What a run does

DocsAlive finds your docs framework, extracts every fenced code block, plans how to test it, runs it in an isolated container, and classifies the result. A run ends with a summary in the terminal plus report.md and report.json.

Run the CLI

You need Python 3.11+ and Docker. Point the CLI at a local checkout or a public Git URL:

# static pass: extract and plan, no execution
docsalive scan ./my-docs-repo

# execute every runnable block in the sandbox
docsalive scan ./my-docs-repo --execute --setup "pip install -q my-sdk"

# or scan a public repository by URL (cloned to a temp dir, deleted afterwards)
docsalive scan https://github.com/your-org/your-docs --execute --setup "pip install -q your-sdk"

--setup runs once per page before its snippets, the way a reader would install your package first. Use it to install the version you're about to release.

Read the report

This is the real summary from one of our test runs (project, commit and directory names redacted):

DocsAlive v0.2.1  ./project-a  framework=mkdocs  pages=24
blocks=204  tested=186  pass=65  fail=111  warn=10  skipped=18  likely-docs-bugs=4
categories: depends-on-context=70, ok=65, runtime-error=17, missing-install-step=10, output-block=10, output-differs=9, missing-fixture=5, network-external=5, not-executable=3, fragment=3, api-drift=2, needs-credentials=2, invalid-syntax=1, stale-output=1, timeout=1
  FAIL BUG? extensions.md:156 [python] api-drift: snippet: parameter `extensions` is not accepted by the current API
  FAIL BUG? extensions.md:174 [python] api-drift: snippet: parameter `extensions` is not accepted by the current API
  FAIL BUG? transports.md:180 [python] invalid-syntax: snippet: is not valid code: invalid syntax. Perhaps you forgot a comma?
  WARN BUG? quickstart.md:118 [pycon] stale-output: ran, but the documented output is Python 2-era (u'' strings) and no longer matches

• blocks: every code block found. tested: executed or syntax-checked. skipped: not runnable on purpose (output blocks, alternate tabs, unsupported languages), each with a reason.
• fail counts every non-zero exit, including snippets that rely on earlier context or need credentials.
• likely-docs-bugs is the number that matters. These are failures a reader would hit, marked BUG? in the list. See Finding categories.

Connect GitHub

With the GitHub App installed on a repository, DocsAlive runs on pull requests, releases and nightly. It posts a check run with annotations on the failing lines and opens draft fix PRs on docsalive/fix-* branches. Permissions are listed on the Security page.

Make docs testable

• Show install steps on the page, or pass them with --setup.
• Put expected output in a separate block right after the code, or use >>> sessions. Both are compared against the real output.
• Mark intentional fragments with .... They're recognized as fragments and not judged.
• Use clear placeholders like YOUR_API_KEY. They're classified as needing credentials, not as bugs.