Why I Built RDX: Bringing Modern "Docs-as-Code" to the Rust Ecosystem

For more than 10 years, I lived and breathed the Node.js ecosystem. I built applications using Node, Bun, and especially Svelte. I loved it. I still do—I’ve never been of the opinion that JavaScript or Node.js is "bad." Tools like Astro, MDX, and SvelteKit are genuinely phenomenal.

But a while ago, my work shifted. I needed more control at a lower level, which led me to Rust. I’ve been using Rust full-time for a while now, and honestly? I don’t plan on going back.

However, moving to a new ecosystem always exposes what’s missing. In Rust, one of the biggest glaring holes is public-facing documentation tooling.

Don't get me wrong: rustdoc and docs.rs are incredible. They are arguably the cleanest, best ways to document source code in the industry. But API documentation isn't product documentation. When you need to build public-facing docs—with rich tutorials, interactive API playgrounds, custom callouts, and interactive tabs—Rust falls short.

You usually end up using mdBook, which is great but visually basic. If you want a modern, interactive documentation site that rivals Stripe or Vercel, you are forced to leave Rust and go back to Python (MkDocs) or the Node.js ecosystem (Docusaurus, Mintlify, Nextra).

I wanted to keep my stack 100% Rust. I didn't want to maintain a package.json just to write my documentation.

I decided to build my own Static Site Generator (SSG) in Rust that runs on WebAssembly (WASM) to fully utilize Rust in the browser. But right out of the gate, I hit a massive blocker: the format.

The MDX and Markdoc Dilemma

Standard Markdown (.md) is too limited. You can't build rich, interactive UI components with it.

The industry standard is MDX. But MDX is tightly coupled to JavaScript. It is inherently imperative—it executes code. Trying to force a Rust backend to safely parse, execute, and render React-based MDX is a nightmare.

Then there is Markdoc (by Stripe). Markdoc gets the philosophy exactly right: documents shouldn't execute code; they should be declarative data. But Markdoc is written entirely in TypeScript/JavaScript. Writing a Rust wrapper around a JS library, or trying to port a massive, moving TS codebase to Rust, felt counter-productive.

I needed a native, high-performance implementation written in Rust.

Introducing RDX: Reactive Document eXpressions

I realized that before I could build the generator, I needed the language. So, I designed RDX.

RDX has everything standard Markdown has, but it supports strict, declarative component rendering. It uses the familiar HTML/JSX-like syntax (<Notice type="warning">) that authors are used to, but it fundamentally treats documents as pure data. No import statements, no JavaScript execution. Just a clean, strictly typed Abstract Syntax Tree (AST).

I didn't just want to build a Rust crate, though. I started by writing a proper, formal specification. I did this so that while I was building the official Rust implementation, anyone else could read the spec and build an RDX parser in Go, Python, or Zig tomorrow.

After finalizing the spec, I built the official tools. Today, I'm thrilled to release them:

• rdx-parser: The core parsing engine built on top of pulldown-cmark.
• rdx-ast: The strictly typed data structures.
• rdx-schema: A validation engine that guarantees your authors don't use fake props or components.
• I've even included a CLI tool to help people convert their existing MDX files to RDX, verify schemas, and more.

Everything is open-sourced, and an be viewed here:

rdx-lang · GitHub

rdx-lang has 4 repositories available. Follow their code on GitHub.

github.com

You can start writing RDX today. In fact, I've already built and published a VS Code/VSCodium extension for syntax highlighting to make authoring a breeze.

The Missing Piece: Rendering (And a Sneak Peek)

Right now, we have the parser, the AST, and the editor support. The only thing missing is the rendering software to turn these .rdx files into a beautiful website.

Don't worry, I'm building that right now.

I am currently developing a next-generation SSG. It will consume your RDX files and generate a documentation site that rivals Docusaurus, Mintlify, and MkDocs. The best part? It uses Rust and WASM to deliver high speed build times and interactive components without ever touching npm.

Built for the AI Era

There is one final reason I believe RDX is the future of "Docs as Code."

RDX is incredibly AI-friendly. If you ask an LLM to write MDX, it frequently hallucinates JavaScript imports or breaks the build with syntax errors. If you ask an LLM to write Markdoc, it struggles with the custom Liquid-style tags.

But LLMs excel at writing standard HTML tags with typed attributes. Because RDX isolates components as pure data and pairs them with rdx-schema validation, you can autonomously generate documentation via AI and validate it instantly at build time. An RDX-powered AI documentation pipeline will beat an MDX or Markdoc pipeline in stability every single time.

But, it will only be like that if everything is done correctly, and I get all the support from the community.

I hope RDX can become the new standard for documentation. We finally have a way to write rich, interactive content without sacrificing the safety, speed, and tooling of the Rust ecosystem.

Check out the repo, read the spec, and stay tuned. The renderer is coming next.