oRPC got Mintlify-level docs inside its own repo.

oRPC is an open-source framework for building APIs that are typesafe end to end, with OpenAPI built in. Developers write procedures, or start from a contract, and get a fully typed client, an OpenAPI spec, and schemas from Zod, Valibot, or ArkType. Around that core, oRPC integrates with Next.js, TanStack Query, NestJS, the AI SDK, Cloudflare Workers, OpenTelemetry, and more.

Its docs cover all of it, for developers who read the code first. 44 pages use Twoslash, so readers can hover over any token in a code example and see the type the compiler infers.

The challenge

Those examples are why oRPC's docs live in its monorepo. The docs are a package there, built against 14 of oRPC's own packages from the workspace, so every Twoslash example checks against the code in the repo, including changes that haven't been released yet. That ruled out hosted platforms like Mintlify, which build docs on their own servers rather than in the repo. The team wanted Mintlify's polish, but the docs had to stay next to the packages.

VitePress handled that well. But Twoslash, Mermaid diagrams, and llms.txt each came from a plugin, and as AI features mattered more to the team, the list kept growing. Each new feature was another dependency to set up and keep current.

The move

Blume runs as a normal package inside a repo, so the docs could stay where they were. Định Lê, oRPC's maintainer, started the move on August 5, 2026, and merged it the next day, less than 24 hours later, in one pull request.

All 96 pages moved to MDX, and none changed its URL. VitePress's containers became Blume's ::: directives, code groups became tabs, collapsible details became expandables, shared snippets were inlined, and the sidebar's order carried over into meta.ts files. The Twoslash blocks and code annotations came across unchanged.

The docs package got lighter, too. VitePress, Vue, Mermaid and the layout libraries it needs, and the plugins for Twoslash, diagrams, and llms.txt, 16 dev dependencies in all, were replaced by one: blume.

What had been plugins came built in, and some features came along that the team hadn't asked for: an Open Graph card for every page, a sitemap, and content signals in robots.txt.

Built around the code

oRPC's readers search for the API they're using, so the team made code searchable. An Astro integration in blume.config.ts adds code blocks to the search index, and the search dialog previews each match as it appears on the page. Others anchor Twoslash popups beside their token, swap in oRPC's own header, and place sponsor slots through the docs.

The theme takes oRPC's pink as its accent, with a dark mode based on the Zed editor's One Dark palette.

Ready for agents

AI features were a big part of why oRPC moved, and now they're defaults or a line of config. The site publishes llms.txt and llms-full.txt, which oRPC links from its header, and a docs MCP server answers at /mcp.

Blume also publishes the agent skills from the monorepo's skills folder, so a coding agent finds oRPC's four skills, for contracts and OpenAPI among them, on the docs site itself.

The results

On October 8, 2026, the oRPC team ran Lighthouse on mobile against /docs/getting-started, on VitePress and on Blume. Each score is the median of three runs, and the Blume page also loaded 76% less JavaScript.

The move kept every URL and every Twoslash example, and the docs section has grown from 91 pages to 122 since. The docs are live at orpc.dev, and their source is public on GitHub. The v1 docs are still at v1.orpc.dev, and redirects send the v1 URLs search engines still index to their v2 pages.

To make the same move, follow the VitePress migration guide.