Testing VitePress documentation examples

The short answer

Build the VitePress site and test its examples as separate checks. vitepress build builds the site for production; a successful build does not establish that commands or code shown in its pages run when a reader copies them. Review the rendered site and its links as well as the outcome of example tests.

DocsAlive reads a VitePress project's Markdown pages in plain Markdown mode. It does not detect VitePress, read .vitepress configuration, run the VitePress CLI, render the site or check links. It can run supported fenced examples, but it does not recognize ::: code-group as a group of alternatives: consecutive fences inside it are each planned independently. Inspect the plan, especially where the page presents mutually exclusive installation paths.

Start with the page a reader sees

VitePress authors write pages in Markdown. The Markdown guide describes fenced code blocks, presentation features, custom containers, code groups, imported snippets and Markdown inclusion. These features can make a page easier to follow, but they also make it important to distinguish the page source, the built page and the code actually exercised by a test.

A page can contain a short JavaScript example, a command to install a package and a result that the reader should expect. Each is a different promise. The code must match the API, the install command must be usable with the stated prerequisites, and the surrounding prose must tell a reader what to do next. A production build is valuable evidence that the site was built; it is not evidence that those promises were executed.

Start an inventory with the entry points readers use: a getting-started page, installation instructions, examples for common tasks and any repository README. Identify each page's source and its dependencies on other pages or files. The static-site guide covers the relationship between source and built site, while the README guide addresses another common entry point.

Fences and highlighting

A fenced block gives a snippet a boundary and can identify its language. VitePress also describes line highlighting for code blocks. Highlighting guides the reader's attention, but it is a presentation choice, not a runtime assertion. If a highlighted line calls an API, a separate check should establish whether that call is valid in the intended environment.

For a raw Markdown scan, the fence info string matters. DocsAlive takes the first word as the language. A plain js or python fence can therefore be planned according to that language. Review the report rather than inferring execution from the rendered color or a fence label. A passing status can reflect execution or syntax checking, depending on the block's treatment.

Keep complete runnable examples distinct from illustrative fragments. If a page intentionally shows only a part of a program, explain what surrounds it. If the page claims a snippet can be copied and run, test it with the dependencies and setup a reader is told to use. A working snippet is strongest evidence when it checks a meaningful result, not merely when it exits successfully.

Custom containers and code groups

The VitePress Markdown reference describes info, tip, warning, danger and details custom containers. They can have titles and contents, including a code block. Their presence changes how content is presented; the instructions inside still need the right prerequisites and an appropriate check. Inspect the built page to see whether a warning or details section communicates the intended context.

A Code Group uses ::: code-group around multiple fences. A fence can carry a label such as js [config.js] or ts [config.ts]. The labels let readers choose a presented example. VitePress also documents imported snippets using <<<, including imports inside code groups. A source file can therefore supply code that is not written directly as a fence in the page being edited.

The following is a fictional page excerpt. The package name illustrates the shape of installation choices; it is not a claim that a package is published. The JavaScript block is self-contained. The installation commands assume their respective package managers are already available.

# Start with the demo

```js
const greeting = 'Hello from the demo';
console.log(greeting);
```

Choose one installation method:

::: code-group

```sh [npm]
npm install acme-docs-demo
```

```sh [pnpm]
pnpm add acme-docs-demo
```

:::

A reader chooses one install method. Test each important choice from an equivalent clean starting environment, then test the later steps that depend on it. Running both commands in one environment is a different journey: the first can affect the second, and a result may not show whether either path works independently. Record which installer and prerequisite state each test used.

DocsAlive does not recognize the VitePress code-group container as an alternatives group. It plans the consecutive fences individually rather than selecting one and skipping the other as alt-variant. Review the plan before treating its result as coverage of the reader's choice. Arrange separate independent tests for the variants that matter. Compare this behavior with the recognized grouping described in the Docusaurus guide and MkDocs guide; do not assume a group syntax has the same treatment across frameworks.

Follow included content to its source

The VitePress Markdown reference describes importing code snippets with <<< and including Markdown with <!--@include: ...-->. Markdown inclusion can be nested and can select a line range. A path prefixed with @ uses the source root; the project root is the default source root unless srcDir is configured. These details help identify which file supplies content to the page a reader sees.

For an included passage, record both the page that presents it and the source file that supplies it. Check whether the surrounding page supplies the imports, setup and explanation required by the included material. A snippet reused in two contexts can work in one journey while the other omits an important prerequisite. A source-file test and a page review answer related but different questions.

A scan of raw page files does not by itself prove that an imported or included passage was expanded and executed as the built site presents it. Inspect the extracted findings, test the source or assembled content separately where needed, and inspect the built page. If the same source is reused, keep a route back to it in the issue so a maintainer fixes the actual authoring location.

Build and preview separately

The VitePress CLI reference says vitepress dev starts a development server using the designated root; in the current directory the dev command can be omitted. vitepress build builds the site for production. Its --base option sets the public base path. vitepress preview locally previews a production build. Use the settings and root appropriate to the actual site.

A successful build shows that the production build completed under that configuration. It does not show that the examples readers copy were executed, that every installation route works, or that a remote service returned the described response. A preview helps a person inspect the built site, including presentation and context, but it is not a substitute for executing examples or checking the links independently.

Keep build failures and example failures distinct in your records. A Markdown rendering issue may need a site configuration or source change; a failing command may need a corrected prerequisite or API call. A code sample can work while being hard to read in the rendered page, and a well-rendered sample can fail when copied. Both observations are useful, with different fixes and owners.

Run supported examples in page context

DocsAlive reads .md, .mdx and .markdown files under the docs directory: docs/ if present, otherwise the repository root, or the folder selected with --docs-dir. It falls back to plain Markdown mode for a VitePress project. It does not read .vitepress configuration or use the VitePress CLI to determine what appears on the site. Compare the files scanned with the site's actual page inventory.

The engine plans supported blocks in page order and runs a fresh container for each page. Earlier steps can provide state for later steps on the same page, which can match a sequential tutorial. A fresh page container also helps reveal a dependency that exists on a maintainer's machine but is absent from the instructions. It does not by itself test a journey that begins on one page and continues on another.

Supported languages include Python, JavaScript, shell, curl and HTTP examples; JSON and TOML are validated. Simple TypeScript annotations are stripped before execution, but other TypeScript-only syntax is not judged. JSX and TSX are not judged. Go, Rust, Java, Ruby and PHP are recognized but not executed. Credential examples are classified, not executed with real keys. Review the frameworks reference and the JavaScript, Python and TypeScript guides for the implications for individual pages.

Keep test-only setup visible. The CLI's --setup command runs at the start of each page container, and can install a dependency needed for the test. If that setup supplies something the page should teach, add or clarify the reader-facing prerequisite rather than silently relying on the harness. The CLI reference describes selection and reporting options.

A generic CI outline

Run these shell commands from the appropriate project root after the site dependencies and product CLI are available. The scan pattern is an illustration; adjust it to match the pages in the repository.

vitepress build
docsalive scan . --execute --include "docs/quickstart*" --out docs-test-report

The first result is the production build; the second is a report about supported extracted blocks. Inspect report.md and report.json in the output directory for skips, reasons and hints. Review the built page and check links separately. The GitLab CI guide describes placing a check in a job; the GitHub Actions guide covers a sibling CI workflow.

Run the checks on changes to pages and APIs, and repeat them periodically to catch drift in dependencies. A scheduled check has value only if someone reviews and routes the result. Keep an owner and a reproduction path for failures, including the source file and the setup used for the test.

Map the page to an executable journey

Before selecting a scan command, write down what a reader is expected to do in order. An installation page may first name a prerequisite, then offer a package-manager choice, then show an import and a small use of the installed package. The useful test is the path through those steps, including a meaningful result. Merely finding a fence on the page does not establish that every prerequisite or alternative was covered.

For each path, note the starting environment, the chosen commands, the expected outcome and the source location to fix if it fails. Keep the test environment clean enough to reveal missing setup. Within one path, preserve state so the import sees the installation and a later example sees earlier variables. For a second package-manager choice, reset the environment and repeat the journey. This makes it easier to tell whether the documented choice itself works.

The page excerpt above deliberately uses a fictional package. It illustrates how alternatives are authored, not a command to run against a real package registry. In a real repository, replace it with the package readers are meant to install and verify the package source and prerequisites. If the check uses a local build while the page tells readers to install a published package, record the difference and provide separate coverage for the published path where it matters.

Compare source scope with the site

VitePress configuration and inclusions can affect the pages a reader sees. The scan's file selection is based on the docs directory and supported file endings, not on reading .vitepress configuration. Compare the actual list of scanned files with the site's intended pages. A file that exists in the repository is not necessarily an important reader entry point, and a reader-visible passage may be authored in a different file from the page that presents it.

Use the report to confirm the extracted fences and their source locations. If an imported snippet or included Markdown passage is absent, identify its source and provide a separate test for the content as used. If it appears in several pages, check each context: a shared sample can rely on an import introduced on one page but missing on another. A single standalone test of the source is useful, but it does not establish that each page teaches the complete journey.

Presentation also deserves its own review. A warning container may provide an essential prerequisite, or a details container may conceal a step the reader needs. Check the built page to make sure the relationship between the text, the container and the example is understandable. Line highlighting can emphasize a change, but the unhighlighted lines still contribute to the runnable program and can break. Review the entire sample as well as the emphasized line.

Keep the result useful to a reviewer

A report should tell a reviewer what was executed, what was validated without execution and what was skipped. Keep the command, selected directory, setup, source location and actual error with the result. For an output mismatch, determine whether the difference changes the page's promise or reflects a variable field. Do not update the documented output simply to make the report green without understanding the difference.

If a page has both a plain supported fence and a code group, examine their treatment separately. The plain fence can be executed according to its language and plan. Each group fence is planned on its own, even though the rendered page presents choices. A combined run does not substitute for clean tests of both alternatives. Link the independent results to the page so a future editor understands the coverage decision.

When the site changes, rerun the production build and the example checks, then inspect the affected rendered page. A change to an included source can affect multiple pages, so review each important use. A change to a package API can affect examples even when the Markdown did not change. Periodic execution helps expose that drift, while the documentation testing checklist helps assign the follow-up.

Triage the result

A finding is evidence to investigate, not an instruction to rewrite the page immediately. Compare the source, selected block, actual error and setup. A missing fixture or a dependency supplied only by a harness may explain the failure. After a change, rerun the affected checks and confirm that the displayed instructions still describe the path tested.

Checklist for a VitePress example test

What this does not replace

DocsAlive does not detect VitePress, read .vitepress configuration, run vitepress dev, vitepress build or vitepress preview, render the site or check links. It does not treat VitePress code groups as alternative tabs. Keep the build, preview, link checks, separate alternative-path tests and human review of the page.

It does not execute Go, Rust, Java, Ruby or PHP. TypeScript handling is limited to simple annotation stripping; other TypeScript-only syntax and JSX/TSX are not judged. Credentials are classified rather than used to execute examples with real keys. A pass can mean execution or a syntax check, so read the report's treatment before describing coverage. The Rust guide explains how to keep native Rust documentation tests, and the docs testing overview describes the wider workflow.

For a starting point, the free health check accepts a public repository you own or maintain; the team runs the engine on up to 40 of its docs pages and emails the real report within 2 business days; the checkout is deleted after the run. Pricing is Open source $0/month, Team $299/month, Growth $699/month, and Scale from $1,499/month.

See how it works and the guides for more ways to organize coverage.

The sources we checked

FAQ

Does vitepress build run code examples?

A successful command builds the production site. It is not evidence that examples were run; use a separate example check.

What does vitepress preview do?

It locally previews the production build. Inspect the result for presentation and context, and use separate checks for executable behavior and links.

Does the product detect VitePress?

No. A VitePress project falls back to plain Markdown mode, and the product does not read .vitepress configuration or run the VitePress CLI.

Are code-group choices treated as alternatives?

No. Consecutive fences in a VitePress code group are planned independently. Test each important reader choice separately from an equivalent clean state.

Are imported snippets automatically proven to run?

Do not assume that from a raw page scan. Inspect findings, trace the source and test the included or assembled content where needed.

What happens to TypeScript examples?

Simple type annotations are stripped before execution. Other TypeScript-only syntax is not judged, and JSX and TSX are not judged.

Can the product test Rust fences?

Rust is recognized but not executed. Keep native Rust tests as described in the Rust guide.

Should I test a page with credentials?

Record the gap and arrange an appropriate separate authorized check. The product classifies credential examples rather than executing them with real keys.