Markdoc is an MIT-licensed, Markdown-based authoring framework and toolchain written in TypeScript, built for teams that need custom documentation sites and content experiences on top of a syntax their writers already know.

What it is

Markdoc is a Markdown-based syntax and toolchain for creating custom documentation sites and experiences. It is published in the JavaScript ecosystem as the @markdoc/markdoc package, written in TypeScript, and licensed under MIT. Its syntax builds on CommonMark, and the project was designed inside Stripe to power Stripe's public docs, described in the README as the company's largest and most complex content site. The toolchain is split into distinct stages: Markdoc.parse turns a document string into an abstract syntax tree, Markdoc.transform converts that tree into renderable content, and Markdoc.renderers.react renders the result into React.

The concrete problem it solves is the gap between plain Markdown and the structured components a real documentation site needs. Markdown alone flattens into simple HTML, so teams that want custom blocks, validated attributes, or component-level control usually hand-roll a parser or reach for a heavier authoring layer. Markdoc replaces that bespoke Markdown-to-component pipeline with a defined parse, transform, and render sequence. Custom tags such as {% image src="/logo.svg" /%} sit directly inside Markdown text, so writers keep writing Markdown while engineers get a structured tree they can inspect and map onto their own components.

Key capabilities

• A three-stage pipeline exposed as Markdoc.parse, Markdoc.transform, and Markdoc.renderers.react, separating parsing from rendering.
• A CommonMark-based custom tag syntax, demonstrated in the README as {% image src="/logo.svg" /%}, which embeds structured directives inside ordinary Markdown.
• A React renderer for turning transformed content into React output, with the README showing Markdoc.renderers.react(content, React).
• TypeScript support with a documented minimal tsconfig.json using "moduleResolution": "node", "target": "esnext", and "esModuleInterop": true.
• Both CommonJS and ESM import paths: require('@markdoc/markdoc') and import Markdoc from '@markdoc/markdoc'.
• MIT licence, which permits commercial and private use without a paid tier.
• A project homepage and documentation set at https://markdoc.dev, plus contributing guidelines and a Stripe-adopted code of conduct in the repository.

Who uses it and how

• Teams maintaining large public documentation sites, following the origin case where Markdoc was built to run Stripe's public docs.
• React application teams that want content authored as Markdown rendered through React components rather than as static HTML.
• TypeScript codebases, where the project documents the compiler options needed before the package will work.
• Writers and engineers sharing one repository: authors write Markdown plus tags, and engineers own the transform and the component mapping.
• Projects weighing ecosystem maturity, with the repository at 8,476 stars, 252 forks, and 29 open issues, and activity recorded as recently as 2026-09-16.

Getting started

Install the library with npm install @markdoc/markdoc, or yarn add @markdoc/markdoc, then import it and call Markdoc.parse, Markdoc.transform, and a renderer. React users install @markdoc/markdoc react @types/react together.

How it compares

No paid products are listed in the facts as products this project replaces, and no comparable tools are named either. On the available facts, Markdoc stands alone in this registry among Markdown-based authoring frameworks.

When to use it — and when not to

A self-hoster operates a Node and npm toolchain, a build step, and, for React usage, a React application; no database, object storage, or SMTP service is mentioned in the facts, so the operational surface is limited to the JavaScript build and runtime. The documented contributor workflow is npm install, npm run build, and npm test, which indicates a maintainer must be comfortable with TypeScript tooling rather than a hosted editor. The README excerpt is sparse: it shows no version numbers, no command-line interface, and no migration path, so anyone wanting a no-code or hosted content platform should not pick it, and anyone who needs a plain Markdown-to-HTML converter without component mapping will find the parse and transform stages unnecessary.

npm install @markdoc/markdoc

yarn add @markdoc/markdoc

const Markdoc = require('@markdoc/markdoc');

import Markdoc from '@markdoc/markdoc';

const doc = `
# Markdoc README

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

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

{
  "compilerOptions": {
    "moduleResolution": "node",
    "target": "esnext", // works with es2015 or greater
    "esModuleInterop": true
  }
}

npm install @markdoc/markdoc react @types/react