Clarify: MDX and OpenAPI docs that stay in your repository

The problem Clarify addresses: docs that drift from the code they describe

Most documentation platforms ask you to move content into their system. Once it is there, versioning it alongside the product becomes awkward, and the rendering layer belongs to someone else's roadmap. Clarify takes the opposite position. The README states that content stays in Git, builds run locally, output is static and portable, and the renderer is part of the codebase.

The intended audience is narrow and identifiable: teams that publish product guides and API references from the same repository, review documentation changes inside normal pull requests, and want to self-host the result. The README lists internal engineering guides, multilingual help centers, and AI-readable knowledge bases as target outputs. If your documentation is edited by people who will not open a pull request, this is the wrong shape of tool.

How Clarify turns clarify.ts, MDX and an OpenAPI file into a static site

The pipeline has three inputs. MDX files under a content folder supply prose and embedded React components. An OpenAPI 3.0 or 3.1 specification supplies API reference pages, and individual operations can be embedded inside MDX guides. A typed clarify.ts file supplies navigation, tabs, sidebars, navbar and footer links, theme tokens, route prefixes, favicon and logo variants, locale behaviour and metadata.

Both clarify dev and clarify build generate Pagefind indexes, so full-text search works in the local preview and in the deployed output, with results scoped to the current language and highlighted excerpts. The build produces one HTML file per route with client-side navigation and copied public assets, plus raw .md and .openapi.* artifacts and an llms.txt file for AI agents. Localized content is organized by locale folders with configurable fallback, and navigation and footer labels are localized in clarify.ts.

The repository is a pnpm and Turbo monorepo. The root package.json is private, declares AGPL-3.0-only, and requires Node at least 22.13.0 and pnpm at least 9.0.0, with pnpm pinned at 11.13.1. Top-level directories include apps/, packages/ and extensions/, which matches the split between the CLI, the renderer and the VSCode extension. The renderer is Tailwind CSS 4 with React 19, exposed through presets, color tokens, radius tokens and layout width settings.

Installing Clarify and publishing a first page

The README gives a two-step start. The init command scaffolds a project directory containing a typed clarify.ts config, MDX pages, public assets, and scripts for local preview and production builds.

npx @clarify-labs/cli init my-docs
cd my-docs

Inside the generated project, install dependencies and start the local site through the project script. The README notes that the same dev script works with pnpm dev or yarn dev if your team uses those package managers.

npm install
npm run dev

Content lives in a source folder. The README shows this layout, with an index page, a guides subfolder and an OpenAPI JSON file sitting side by side.

source/
├── index.mdx
├── guides/
│   └── writing-content.mdx
└── api.openapi.json

When the site looks right locally, produce the static output. The README states that the generated output/ directory can be deployed to any static host.

npm run build

The CLI can also be invoked directly from a documentation project with npx clarify dev and npx clarify build. Configuration changes such as navigation, OpenAPI references, theme tokens, locale behaviour and metadata all go into clarify.ts.

The VSCode extension and what it does not replace

Clarify ships a VSCode extension that provides live preview with hot module replacement while you edit MDX, OpenAPI specs or config files. It detects a Clarify project by the presence of clarify.ts in the workspace, resolves the preview route from the file you have open, and can start and stop the dev server from the editor. Installation is manual: download the .vsix from the GitHub Releases page and install it, either from the command line or through the Extensions sidebar.

code --install-extension clarify-vscode-extension-*.vsix

The extension is a convenience layer over the same dev server, not a separate editing environment. There is no hosted editor and no content API described in the README, so the extension does not change the underlying requirement that authors work in files.

Where Clarify gets in the way

The licence is the first constraint. The repository declares AGPL-3.0-only. If you customize the renderer and expose the modified version to users over a network, that licence carries obligations you should have a lawyer read. The README does not discuss licence implications, and it does not offer a commercial exception.

The second constraint is the toolchain. Node 22.13.0 or later and pnpm 9.0.0 or later are declared in the root package.json engines field. A team pinned to an older Node LTS in CI will have to move before Clarify builds. This is not a documentation problem, it is a build-environment problem, and it surfaces on day one rather than later.

The third is authoring model. Everything routes through MDX and TypeScript. There is no visual editor, no CMS integration, and no non-developer workflow described in the README. A technical writer who does not use Git cannot contribute through the documented path. The README also does not document rollback behaviour, versioned documentation sets, or how a breaking change to clarify.ts is migrated between releases. Those are real gaps if you plan to pin a version for a long-lived site.

Clarify compared with Mintlify and VitePress

The README addresses Mintlify directly. It describes Mintlify as a polished hosted documentation platform and positions Clarify as the open-source, codebase-owned alternative: same category of modern docs experience, different ownership model. The practical difference is where the rendering and deployment live. With a hosted platform, the renderer and the deployment pipeline are operated for you. With Clarify, the renderer is in the codebase and the output is static files you deploy yourself, which means you also carry the upgrade work.

VitePress is a closer comparison on mechanics, since both are static site generators driven by files in a repository, and the repository lists vitepress among its topics. The difference the README implies is scope: Clarify bundles OpenAPI reference generation, Pagefind search, locale folders with fallback, and llms.txt output into the same pipeline, where a VitePress setup would assemble those from separate plugins and conventions. That bundling is the selling point and also the lock-in: adopting Clarify means adopting its config schema and its plugin hooks for route resolution, virtual modules and build completion.

Maintenance, upgrades and what the release cadence implies

The last push to the default branch was on 2026-08-26, and the most recent release, v0.11.21, is dated the same day. The two releases before it, v0.11.20 and 0.11.19, landed on 2026-08-24 and 2026-08-13. The version number sits at 0.11.x, which means the project has not declared a 1.0 stability commitment, and the release notes for these versions are not published in the repository, so nothing here establishes whether config keys are stable across minor versions.

For upgrade cost, the practical exposure is clarify.ts. It is TypeScript, so a schema change shows up as a type error at build time rather than as a silently wrong page, which is the better failure mode. The monorepo layout with apps/, packages/ and extensions/ also means the CLI, renderer and VSCode extension version separately in principle, even though the README presents them as one product. Pin the CLI version in your project rather than relying on npx resolving the latest release on every build.

Editorial conclusion

Adopt Clarify if your docs already live in Git and you want API reference, search and llms.txt output without a hosted platform holding your content. Do not adopt it if you need a non-technical editing interface, or if AGPL-3.0 obligations on a customized renderer are a problem for your legal team. Before committing, verify that Node 22.13 and pnpm 9.0 are acceptable in your build environment, and that the clarify.ts config surface covers the navigation and locale behaviour you need.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. taicode-labs/clarify on GitHub