Write Docs Like Stripe Does: Meet Markdoc, the Markdown Framework Behind stripe.com/docs

You've probably written documentation before, and you know the drill: Markdown is great for simple pages, but the moment you need custom components, reusable snippets, or any real logic baked into your docs, you're either wrestling with a static site generator's plugin system or hand-rolling something fragile. What if you could keep writing in Markdown but get the power of a real programming language underneath? That's exactly the problem Markdoc set out to solve.

Markdoc is a Markdown-based syntax and toolchain for building custom documentation sites and experiences. It's the framework that powers Stripe's public docs—their largest and most complex content site—and now it's open source under the MIT license.

What It Does

At its core, Markdoc is a parsing and rendering pipeline. You feed it a Markdown string, it produces an abstract syntax tree (AST), you transform that AST, and then you render it to whatever output you need—React, for example.

The workflow looks like this:

const doc = `
# Markdoc README

{% image src="/logo.svg" /%}
`;

const ast = Markdoc.parse(doc);
const content = Markdoc.transform(ast);
return Markdoc.renderers.react(content, React);

You parse, you transform, you render. That middle step—the transform—is where the magic happens. It's where you can inject custom logic, validate content, or reshape the tree before it hits your UI.

The project is built for JavaScript environments. You install it via npm or yarn, import it as CommonJS or ESM, and if you're using React, there's a straightforward integration path. TypeScript users get first-class support too, with a minimal tsconfig.json documented in the README to get you going.

Why It's Cool

The thing that makes Markdoc stand out isn't the parsing—plenty of libraries can parse Markdown. It's the philosophy baked into the design.

• Custom syntax that still looks like Markdown. Notice the {% image src="/logo.svg" /%} tag in the example above. That's Markdoc's way of letting you drop in custom components without leaving Markdown behind. You're not writing JSX in your docs or configuring some convoluted shortcode system. You're writing something that reads like a natural extension of Markdown itself.

• It's built for scale. Stripe's docs are massive, with thousands of pages covering APIs, SDKs, guides, and reference material. Markdoc wasn't designed for a personal blog with five posts—it was designed to handle complex, interconnected documentation at enterprise scale. That's a strong signal that the architecture has been battle-tested.

• The pipeline is transparent. Parse, transform, render. Three distinct phases, each one giving you a hook to intervene. You want to lint your docs during the transform phase? Go for it. You want to render to something other than React? The renderers object suggests there's room to build your own. The design doesn't lock you into a single output format.

• It's approachable. The README is refreshingly short. Install, import, parse, render. That's the whole getting-started flow. For a framework that powers one of the most complex docs sites on the internet, the entry barrier is remarkably low.

How to Try It

Getting started is straightforward. First, install the library:

npm install @markdoc/markdoc

Or if you prefer Yarn:

yarn add @markdoc/markdoc

If you're using React, you'll also want to grab the React types:

npm install @markdoc/markdoc react @types/react

Then import it into your app and run the basic pipeline. The README shows the core usage in a few lines, and the full documentation lives at markdoc.dev. For TypeScript users, the README includes a minimal tsconfig.json with moduleResolution set to node, target set to esnext (or anything from es2015 up), and esModuleInterop enabled.

If you want to contribute, the project has contributing guidelines, a code of conduct (adopted from Stripe), and a straightforward development workflow: npm install, npm run build, then npm test. The repository is at github.com/markdoc/markdoc, and it's MIT licensed.

Final Thoughts

Markdoc is worth a look if you're building a documentation site that's outgrown plain Markdown but you don't want to commit to a full JavaScript framework for your content layer. It's especially relevant if you're working on developer-facing docs where you need custom components, reusable patterns, and a clean separation between content and presentation. That said, if your docs are simple and static, this might be more machinery than you need—a plain static site generator would do the job with less overhead.

But if you're staring down a growing docs site and dreading the complexity that's coming, Markdoc offers a path that keeps your content authoring simple while giving your engineering team the hooks they need to build something robust. It's the framework Stripe uses for its own docs, and now it's yours to play with. The full documentation at markdoc.dev is a good next stop, and the repo is open for contributions.

Follow @githubprojects for more developer tools and open source projects.