MDX gives you React components in your docs. DocsCI makes sure every code block in every .mdx file actually works — before you deploy.
.mdx
files parsed natively
< 2 min
setup time for most Next.js repos
8 min
median fix time per finding
Free
up to 100 runs/month
Next.js-based docs sites (Nextra, Mintlify, custom App Router setups) are powerful, but code blocks in MDX files are just strings — they're never executed. When your SDK changes, those examples break silently.
Point DocsCI at your Next.js docs repo. It parses .mdx files, extracts code blocks by language, executes them in hermetic sandboxes, and checks heading structure and accessibility. Results appear as inline GitHub PR comments.
Parses .mdx and .md files natively. Extracts fenced code blocks by language tag, skips non-executable blocks (like shell output marked with 'text'), and respects disable comments.
Runs JS/TS code blocks in V8 isolates with your type definitions injected. Catches TS type errors and runtime exceptions that would confuse users copying your examples.
Python examples in MDX execute via Pyodide WebAssembly — full CPython in the browser sandbox. No native dependencies to install. Catches ImportErrors from renamed modules.
If you use custom MDX components (like <CodeGroup>, <Tabs>, <Callout>), DocsCI can validate that props match your component definitions — catching refactors that break examples.
Heading hierarchy, image alt text, link text quality — all checked on the MDX source. axe-core rendered checks available for deployed Vercel previews.
DocsCI can run against your Vercel preview deployments. Catches rendering issues and component errors that only appear after the MDX is compiled.
Tell DocsCI where your .mdx files live and which code block languages to execute. One line per language.
# docsci.yml
snippets:
extensions: [".mdx", ".md"]
languages:
javascript: true
typescript: true
python: true
bash: false # validate structure only
text: false # skip — output blocks
component_defs: "components/mdx/" # optionalYour GitHub Action archives the docs directory and submits it. DocsCI handles parsing, execution, and accessibility checks.
# .github/workflows/docsci.yml
- name: Run DocsCI on MDX docs
run: |
tar czf docs.tar.gz pages/ content/ *.mdx *.md 2>/dev/null
curl -sf -X POST https://snippetci.com/api/runs/queue \
-H "Authorization: Bearer ${{ secrets.DOCSCI_TOKEN }}" \
-F "docs_archive=@docs.tar.gz"PR comments point to the exact .mdx file and line. Suggested fixes include the corrected code block. Accept, commit, and DocsCI re-runs.
## ❌ DocsCI — Snippet failure — content/quickstart.mdx:84
```typescript
// Your example (line 84):
import { createClient } from '@example/sdk/v2';
// ❌ Module '@example/sdk/v2' not found.
// Suggested fix:
import { createClient } from '@example/sdk';
```Does DocsCI work with Nextra, Mintlify, and other Next.js doc frameworks?
Yes — DocsCI reads the raw .mdx source files, not the rendered output. It works with any framework that uses standard Markdown fenced code blocks. Framework-specific components are also supported.
How does DocsCI handle MDX imports and custom components?
For code execution purposes, custom MDX component imports are stripped — only the fenced code block content is executed. For component prop validation (optional), you provide your component definition directory.
Can I run DocsCI on Vercel preview deployments?
Yes. You can pass a docs_site_url to DocsCI alongside the archive, and it will run axe-core against your preview URL for rendered accessibility checks.
What about TypeScript examples that import from my own packages?
You can include a type_stubs archive with your .d.ts files. DocsCI injects these into the V8 isolate so TS examples compile correctly against your type definitions.
Is there a way to skip specific code blocks?
Yes — add a comment `{/* docsci-skip */}` before the code block in your MDX file, or use the `docsci.yml` skip_patterns config to exclude blocks by content pattern.
Join API and platform teams who use DocsCI to ship verified documentation.