Testing Docusaurus documentation examples

The short answer

Test Docusaurus documentation examples as reader journeys as well as building the site. Run the production build with the site's actual configuration, inspect its link diagnostics, and separately execute the supported commands and code in clean environments. A build can succeed while a package name, API call or displayed result is wrong. A passing example can coexist with a broken page or link.

Start with the docs source and docusaurus.config.js, identify each fenced example and its prerequisites, and map tabs to alternatives. Run the steps in each page in order, then investigate the first failure with the environment and actual error in view. Keep skipped examples visible: a result for one install tab does not establish that every package manager works.

DocsAlive detects Docusaurus from docusaurus.config.*, reads MDX, recognizes Tabs as alternatives and picks one variant per group. It plans supported blocks in page order and uses a fresh sandbox container per page. It reports failures and their classifications, along with deliberate skips. It does not build or render the site, check links or test React components; keep those checks alongside it. The docs testing overview explains the wider approach, and how it works describes the pipeline.

Find the source and define the test scope

The Docusaurus configuration reference places docusaurus.config.js at the site root; it may be named docusaurus.config.ts in a TypeScript codebase. The Markdown features documentation describes the Markdown and MDX features that pages can use. Begin at the actual site root and inspect the repository's layout before selecting files. In a larger repository, the site root and repository root may be different, and an example scan pointed at the wrong directory can give a misleadingly small result.

Make an inventory of the pages intended for the test, their fenced blocks and the reader tasks they support. Record the page path and source line for each finding so the maintainer can locate it. Include installation instructions, quickstarts and API examples, not just blocks that look like complete programs. A shell command can be the first step of a tutorial even when its result is used only by later code.

Compare the inventory with the test report. A page omitted by an include pattern is different from an included page whose examples were skipped. A block may be present but intentionally illustrative, require credentials or use a language the runner does not execute. The useful question is not simply how many blocks exist; it is which promises have evidence and which still need a different check. The static-site guide covers the distinction between page source, the build and the site readers see.

Use the build and link settings as separate evidence

The CLI reference says docusaurus build compiles the site for production. Run it with the configuration and dependencies intended for the site, and retain its diagnostics. A successful build is evidence about that compilation under those conditions. It is not evidence that a reader can install a package, authenticate, call an API or reproduce a code block's output.

The configuration reference documents onBrokenLinks and related handling for broken Markdown links and anchors. These settings determine how particular link problems are reported or treated, so inspect the actual configuration and diagnostic rather than assuming every link problem fails every build. The reference says onBrokenLinks controls detected broken links and defaults to throwing an error; detection is available in the production build. onBrokenAnchors applies to broken anchors declared with the Docusaurus Heading component and defaults to a warning. The older onBrokenMarkdownLinks setting is deprecated in favor of markdown.hooks.onBrokenMarkdownLinks. A warning and an error are different signals; ignored diagnostics are not evidence of working links. Review the applicable settings when the team changes its build policy.

Even a useful link diagnostic has a limited scope. It does not execute a shell command shown next to the link, verify that an external service behaves as the page promises, or establish that an interactive component works for a reader. Conversely, an example test does not validate site navigation. Keep the build result, link review and example report distinct enough that a reviewer knows what passed.

When a build fails, find the relevant page or config diagnostic and reproduce with the same configuration. When an example fails, inspect its command, prerequisites and actual error. These investigations can touch the same page but answer different questions. A build fix should not silently remove a failing example without deciding whether the reader still has a complete path.

Read code blocks as both source and presentation

The code blocks reference describes a language meta string for syntax highlighting, a title after the language, line ranges in metadata, and line-highlighting comments. It also describes line numbers and custom magic comments. With the live-code-block plugin, a block marked live can become an interactive editor. Those features affect what a reader sees and uses; they are not a guarantee that the source runs in the environment you intend to test.

The distinction matters especially for magic comments: the source says these directives are parsed and removed for presentation. A test reading the fenced source and a reader copying the rendered block may encounter different text. Check that the chosen test covers the reader-visible code and that any comment syntax is appropriate for the language. If line ranges are used, inspect the rendered emphasis after edits so a highlighted line still supports the surrounding explanation.

A title may identify a file the reader should create. Treat that filename and its role as part of the instruction, even if an execution tool reports only the block's source location. If the next command expects the file, verify that the reader has been told where to save it. Syntax coloring helps readers understand a block, but it does not show that the labeled language is supported by an example runner or that dependencies are installed.

For a live editor, separately inspect the interactive experience and the resulting behavior. A source-block execution result cannot demonstrate that the editor loads, that its controls work, or that the displayed result matches the surrounding prose. Similarly, a visually correct block is not a substitute for running a copyable command in a clean environment. Keep both forms of evidence when the page relies on both.

Separate MDX page components from reader examples

Docusaurus supports MDX and React in documentation, including imports and JSX in a page. An import of a tab component is part of assembling the page; it is not automatically a command that the reader should run. JSX used to render a callout or component can be essential to the site while having no role in a tutorial's runtime environment.

Identify the fenced blocks that make reader-facing promises and trace the prose around them. An MDX page may put an installation command inside a component, then use a normal fenced block later to demonstrate an API. The component supplies page structure; the two fenced blocks may form a sequence. Do not concatenate the page's React imports with a reader's shell session or report a component import as a missing tutorial dependency.

Component behavior deserves its own build and browser review. Check whether tabs show the right content, labels identify the choices, and formatting preserves the code readers should copy. If a component changes the visible instructions, check the resulting page as well as the authored source. The JavaScript documentation testing guide covers runtime examples; page component checks answer a separate question.

Treat tabs as alternative paths

The Tabs reference describes Tabs and TabItem components. Related groups with the same groupId synchronize choices; when a selected value is missing from another group, that group does not change to that value. This behavior affects the journey a reader sees across a page. Inspect the labels and values as well as the code under each tab.

Here is an illustrative MDX page excerpt. @acme/docs-demo is fictional, so the install commands are examples of documentation structure, not commands to validate a real distribution.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Install the demo

Choose the package manager available in your environment.

<Tabs groupId="package-manager">
  <TabItem value="npm" label="npm">

```bash
npm install @acme/docs-demo
```

  </TabItem>
  <TabItem value="yarn" label="Yarn">

```bash
yarn add @acme/docs-demo
```

  </TabItem>
  <TabItem value="pnpm" label="pnpm">

```bash
pnpm add @acme/docs-demo
```

  </TabItem>
</Tabs>

A reader normally chooses one installation method. Running all three consecutively in a single environment would test a different path and can conceal a missing prerequisite. Test each variant you promise from an equivalent clean starting state, with the selected package manager available. Follow each choice through any subsequent commands that depend on the installation. If another synchronized group supplies run commands, verify that each matching value leads to a coherent end-to-end path.

DocsAlive recognizes tab groups as alternatives, picks one variant and marks the others alt-variant. Its selection is not evidence that all npm, yarn and pnpm instructions passed. Review the report, record the chosen path, and arrange separate checks for the remaining variants. Do not infer synchronized browser behavior from a source scan. The installation testing guide offers more on isolating install paths.

Run each page in a clean container

A page often introduces a variable, creates a file or installs a package before using it. Run dependent blocks in their documented order, preserving state within that page. Start a new clean environment for the next independent page so that a previous installation does not accidentally satisfy an undocumented prerequisite. If a tutorial explicitly crosses pages, also test that complete journey separately: isolated page runs cannot by themselves establish the handoff.

DocsAlive keeps blocks in page order and starts a fresh container per page. Containers run as an unprivileged user with a read-only root filesystem, dropped Linux capabilities, no privilege escalation, and resource and time limits. The plan can execute, syntax-check or skip a block with a reason. It extracts an output block shown immediately after code for comparison. A pass can therefore mean execution or a syntax check; inspect the treatment before describing a whole page as executed.

Separate test harness setup from instructions readers receive. The CLI's repeatable --setup runs a shell command at the start of each page container. This can provide a necessary environment, but it can also mask a missing installation instruction if nobody records it. Note the package or artifact under test, the setup command, and whether the page tells the reader to perform an equivalent step. The CLI reference explains selection and reports.

Network access, external services and local fixtures also influence results. A test with no network answers a different question from an install that must download a package. If a page expects a local file, either document how the reader obtains it or clearly describe it as a prerequisite. Keep the first error and surrounding evidence; later failures can merely follow from an earlier missing step.

A generic CI outline

From the site root, with site dependencies and the product CLI already available, the following shell commands illustrate separate checks. The build command assumes the site's build script invokes docusaurus build; use the site's actual invocation if it differs. Adjust the scan target and include pattern to the repository layout.

npm run build
docsalive scan . --execute --include 'docs/**' --out docs-test-report

Review docs-test-report/report.md and docs-test-report/report.json, including categories, reasons, hints and skipped blocks. The scan runs supported extracted examples according to its plan; it does not run the build command on your behalf. If the docs need a specific setup, add a documented --setup command and consider whether it hides a reader-facing omission. Repeat checks for relevant changes, releases and dependency drift, keeping a record of the artifact tested. The quickstart testing guide helps map a longer path.

Choose what a passing result means

Before wiring the checks into a required workflow, agree on the evidence a reviewer needs for each type of page. An install page should identify the package and the environment in which its command was tried. A tutorial should show that its later steps received the state created by earlier ones. A reference example may need an assertion or a stable output comparison to establish more than successful process completion. Record the selected artifact and prerequisites with each result.

Coverage can change without a page disappearing. A new tab, a change from JavaScript to JSX, or a newly credential-gated request can turn a previously executed path into a skip. Compare skips and selection with the previous review, and give an owner to important gaps. If the test harness supplies setup on every page, periodically check the instructions without that hidden help so an omitted installation step stays visible. A passing build and passing selected examples are valuable evidence when their limits are clear to the person approving the change.

Triage failures before editing

A nonzero result is a starting point for investigation. Compare the actual error with the documented steps, the installed artifact and the setup supplied by the test. DocsAlive classifies results using the actual error rather than the exit code alone. Its report includes a category and reason so a maintainer can distinguish likely documentation bugs from environment and coverage issues.

Timeouts, runtime errors and some external network results need review rather than automatic treatment as docs bugs. Output can differ because of timestamps or ordering, but a changed value may be material. Preserve actual and expected output until someone understands the difference. Fix the source, rerun the relevant page, and confirm that the correction does not invalidate another tab or later step.

The API reference testing guide is useful when an example depends on a changing API. For a repository landing page outside the docs tree, add a README check. Each reader entry point can make a different promise even when the snippets look similar.

Checklist for a Docusaurus example test

Use the broader docs testing checklist to assign owners and decide when each check runs. A skipped path remains a coverage decision even when every executed block passes. Review the inventory after navigation, package-manager choices or the page's prerequisites change.

What this does not replace

DocsAlive does not build or render a Docusaurus site, check links, or test React components. Keep the production build, link diagnostics and browser review. Human review is still needed for clarity, accessibility and whether the prose teaches the intended task. A command that executes can still be the wrong command for the reader.

JSX and TSX are not judged yet, and full TypeScript is not judged; simple type annotations can be stripped for execution. Go, Rust, Java and other recognized languages are not executed. Credential examples are classified rather than executed with real keys; customer-provided test credentials are not currently supported. Record these boundaries in the report and use separate checks for important untested paths.

The free health check lets you send 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.

The sources we checked

FAQ

Does docusaurus build run documentation examples?

The command compiles the site for production. A successful build does not establish that the commands and code shown to readers execute successfully. Run an example check separately and keep both results.

Do broken-link settings prove all links work?

The settings govern how relevant link problems are handled. Inspect the actual settings and diagnostics; a warning or ignored issue is not a passing link test. Link checks also do not validate the code on a destination page.

Should every package-manager tab be tested?

Test every variant you promise, from equivalent clean environments. DocsAlive selects one variant per group and skips the others, so one run leaves alternatives to cover separately.

Does groupId test synchronized paths?

It synchronizes related choices in the site. It is not an execution test. Inspect the rendered groups and separately run the commands for each coherent reader path, including later steps.

Are MDX imports runnable examples?

Imports and JSX used to assemble a page are page implementation. Identify the fenced code intended for readers, and test the React components through a separate site check.

Why preserve block order?

A later block can depend on an earlier installation, variable or file. Preserving the sequence models the page; starting each page clean helps reveal prerequisites that were never supplied.

What does an alt-variant skip mean?

The block is another choice in a group and was deliberately not run in that selection. It is not a pass or a failure. Record the untested path and arrange coverage if readers are promised it.

Can the product replace a site review?

No. It does not render the site, check links or test React components. Continue those checks alongside execution. For another MDX framework's workflow, see the Mintlify testing guide.