Markdoc is a Markdown-based syntax and toolchain for creating custom documentation sites and experiences.
We designed Markdoc to power Stripe's public docs, our largest and most complex content site.

To get started with Markdoc, first install the library:

pnpm add @markdoc/markdoc

and import it in your app:

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

or if you are using ESM

import Markdoc from '@markdoc/markdoc';

then use Markdoc in your app or tool:

const doc = `
# Markdoc README

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

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

Check out our docs for more guidance on how to use Markdoc.

The public renderer types require @types/react, even when using only the Markdown parser or HTML renderer. Package managers that install peer dependencies automatically will install it; otherwise, install @types/react explicitly. The React runtime is optional.

For TypeScript projects that use a bundler, use:

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

For code run directly by Node.js, use "module": "nodenext" and "moduleResolution": "nodenext" instead.

If you are using React, install Markdoc with:

pnpm add @markdoc/markdoc react @types/react

Contributions and feedback are welcome and encouraged. Check out our contributing guidelines on how to do so.

For development, use the Node version in .node-version and pnpm, with the version pinned in package.json. If using Corepack, run corepack enable first.

This repository uses pnpm workspaces and Turborepo:

• packages/markdoc contains the published @markdoc/markdoc library, its tests, and build configuration.
• packages/* is the home for additional packages.
• apps/* is the home for applications.

Run these commands from the repository root:

1. Run pnpm install
2. Run pnpm run build
3. Run the tests using pnpm test
4. Check the built package's TypeScript declarations using pnpm run test:types

Add release notes with pnpm changeset. See the Changesets guide for versioning and the release process.

Run pnpm run check for all CI checks. Turborepo builds workspace dependencies first and caches build outputs in each package's dist directory.

To work on Markdoc alone, use pnpm --filter @markdoc/markdoc test or pnpm exec turbo run build --filter=@markdoc/markdoc.

New packages and apps should declare their own scripts and use workspace:* for dependencies on other workspaces. Applications should set "private": true. Packages with build outputs other than dist should configure those outputs in a package-level turbo.json.

This project has adopted the Stripe Code of conduct.

This project uses the MIT license.

Special shout out to:

• @marcioAlmada for providing us with the @markdoc GitHub org.
• @koomen for gifting us https://markdoc.dev.