Vocs: a portable documentation framework that type checks your examples

What Vocs is

Vocs is a portable documentation framework powered by Vite, and the repository describes it as minimal docs for agents and humans.

That tagline is the design brief in five words. The human half is a documentation site built from Markdown and MDX, and the agent half is a set of files that an automated tool can read. The topics make the same point from the other side, listing docs, markdown, mdx, react, typescript and vite, which is a documentation tool that compiles rather than one that renders at request time.

The Vite part is the interesting choice. A documentation framework that runs on the same build tool as the rest of a modern TypeScript project gets the same local development experience, the same plugin ecosystem and the same deployment output, and the difference between a documentation site and the rest of a project's tooling shrinks to nothing.

The project is written in TypeScript, the licence is MIT, and the site is vocs.dev, which is also where the documentation and guides live. The npm package is vocs, and the recent releases are 2.10.3 from 2026-10-14, with 2.10.2 and 2.10.1 both from 2026-10-05. The last push to the repository was on 2026-10-15, so this is a project shipping often.

The community is split in the way the readme describes it, with GitHub discussions for anything that benefits from being searchable and a Discord for casual conversation, both under the Wevm organisation.

The build, and what runs in what order

The build script is the clearest statement of how the pieces fit, and it is a chain of five steps.

    "build": "pnpm --filter create-vocs build && pnpm --filter @vocs/twoslash-rust build && pnpm --filter @vocs/twoslash-rust build:npm && node scripts/build-openapi-standalone.ts && zile",

So the scaffolder is built first, then the Rust type checker, then the npm package of that type checker, then a script that produces a standalone OpenAPI build, and then the publishing tool itself.

The order is not arbitrary. The type checker has to exist before the OpenAPI build can use it, and both have to exist before the final packaging step runs, which is why the Rust component is built twice, once as a workspace package and once as a standalone npm artefact.

The development scripts follow the same split, with a dev script that starts the scaffolder and then the dev server, a separate playground script for the example workspace, and a playground script specific to the type checker.

The documentation site has its own scripts, for building, developing and previewing the site directory, and the twoslash command runs the type checker over the documentation itself, which is the neat part. The same mechanism that type checks the examples in your documentation can be pointed at the framework's own documentation.

The scaffolder, the playground and the site

The repository layout shows a framework with three working surfaces rather than one.

There is the src directory with the framework itself, the site directory which is the documentation site built from it, the playground directory which is a scratch workspace for trying things, and the create-vocs directory, which is the scaffolder that creates a new documentation project.

The scaffolder is a separate package with its own build and dev scripts, and it is wired into the root build, which means a new project is created with a command rather than by copying a template by hand. That is a meaningful part of a framework, because the difference between a good first run and a bad one is usually the configuration of the thing that generates the project.

The playground is where the examples live, and it has its own script in the root package, plus a separate script for running the type checker against the playground, which suggests the playground is a testbed for the type checking behaviour as much as for the framework.

The type checking of examples is implemented twice, and that is the most interesting piece of engineering in the repository. There is a TypeScript implementation, the twoslash package, and there is a Rust implementation in the twoslash-rust directory with its own Cargo manifest, and the Rust one is tested with a cargo test invocation against its own manifest.

So a documentation framework has a Rust component in it, and it ships the Rust component to npm, which is an unusual and pragmatic arrangement: the performance and the deployment story of a native binary, delivered to a JavaScript toolchain as a package.

Type checked code samples, and OpenAPI

The OpenAPI step deserves a mention because it is the least obvious part of the build.

The script named for building an OpenAPI standalone artefact is part of the release chain, and it runs between the type checker build and the final packaging. So the framework can produce an OpenAPI document as a separate artefact, and the type checking infrastructure is shared between the two jobs.

That is the kind of thing a documentation framework needs when it is used to document an API, and the fact that the standalone build is a first class step rather than an afterthought tells you that API documentation is a supported use, not a hack.

The type checking itself is the feature that separates this from a markdown renderer. The idea is that a code sample in the documentation is not text, it is code that the compiler checks, so a sample that stops compiling fails the build rather than shipping. The playground scripts and the docs twoslash script are the entry points for that, and the Rust implementation is there because the check has to run fast enough to sit inside a build loop.

The type dependencies tell you how the pieces fit, with the syntax tree types for the common Markdown and HTML trees, a JavaScript parser for the ECMAScript syntax tree, a document object model implementation for testing, and Mermaid for the diagrams. The Mermaid dependency is a small but telling detail, because it means a documentation framework in this family treats diagrams as a first class citizen rather than as an image you paste in.

The toolchain, and how a release is made

The release process is built on three tools, and they are worth naming because the combination is unusual.

The version step is a plain changeset version. The publish step is a build, then two calls to the publishing tool for the prepare and post stages, then the changeset publish itself.

    "changeset:version": "changeset version",
    "changeset:publish": "pnpm build && zile publish:prepare && changeset publish && zile publish:post",

So changesets handle the version and the changelog, and the publishing tool handles the prepare and post steps around the actual publish. That is a clean separation, with the conventional tool doing the conventional job and the other one handling the parts that are specific to this project.

The rest of the toolchain is modern and worth a look. The package manager is pnpm at a pinned version, with a workspace file, and the node version is pinned through the devEngines field. Linting and formatting are done by biome with a single check command that fixes and applies the unsafe rules. Type checking is a project build with the compiler, and the tests run under vitest against the source directory, with a separate cargo test command for the Rust component.

The dependencies tell you the shape of the renderer. React and React DOM are there, along with the React server components package for the web pack integration, Waku for the application framework, and Vite for the build. The tree types and the MDX types are the input side, and the parsing and stringifying libraries are what the type checker and the MDX pipeline use to work on code.

The state of the project, and who it is for

A few observations about where the project is.

The release cadence is high. Three releases in the first two weeks of October 2026, with the last push the day after the 2.10.3 release, and the version numbering shows a project that has moved past its first year and is now working on polish rather than on shape.

There is a roadmap file and a changelog at the root, and a file for agents in the repository, which is a small signal that the project takes machine readers seriously enough to put conventions in the tree rather than only in the readme.

The contribution guidance is explicit about reading the contributing guide before opening a pull request, which is a small thing that reduces the noise in a project with this release rate.

So who is it for. A project with a documented API, a team that cares that its examples compile, and no desire to run a documentation platform. The output is a static site, which means the hosting decision is separate from the framework decision, and the build output is something you can put behind a CDN or on a static host without a server process.

The trade is that you are adopting a framework rather than a service, so the setup is yours to own. In exchange you get documentation that is a static artefact, with type checked examples, produced by a build step you can run in continuous integration next to your tests.

Editorial conclusion

Adopt Vocs if your documentation has code samples that should keep compiling, because the type checking pipeline is the part of the framework that is hard to reproduce by hand. Do not adopt it if you need hosted documentation with accounts and a search backend, since the output is a static site. Before you commit, read the build script, because the release path runs the scaffolder, the Rust type checker and the OpenAPI build before publishing, and knowing the order tells you what a broken build is telling you.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. wevm/vocs on GitHub