Markdoc — Powerful Markdown Authoring Framework by Stripe

Introduction

Markdoc is a Markdown-based authoring framework created by Stripe for building documentation. It extends standard Markdown with a custom tag syntax, attribute annotations, and a schema-based validation system, letting teams create richly interactive documentation pages while keeping content in readable Markdown files.

What Markdoc Does

• Extends Markdown with custom tags, nodes, and functions using {% tag %} syntax
• Validates documents against a schema to catch errors at build time
• Transforms parsed content into a renderable tree for React, HTML, or any target
• Supports variables and conditional content for dynamic documentation
• Provides a plugin architecture for custom transformations

Architecture Overview

Markdoc's pipeline has three stages: parse, transform, and render. The parser builds a Markdown AST extended with tag nodes. The transform stage applies a schema (defining tags, attributes, and validation rules) to produce a render tree. Renderers then convert the tree to React components, HTML strings, or custom output. The schema is plain JavaScript, making it easy to define new tags.

Self-Hosting & Configuration

• Install the @markdoc/markdoc npm package in your project
• Define tag schemas in JavaScript files that specify attributes, children, and validation
• Use the Next.js plugin (@markdoc/next.js) for file-based routing of Markdoc pages
• Content files use the .md or .markdoc extension and live alongside code
• Integrate with any static site generator or server-side framework

Key Features

• Clean, readable syntax that stays close to standard Markdown
• Schema validation catches documentation errors before deployment
• First-class React rendering for interactive components inside docs
• Variables and functions enable conditional and dynamic content
• Created and battle-tested at Stripe for their public documentation

Comparison with Similar Tools

• MDX — embeds JSX in Markdown; Markdoc uses a tag syntax that non-developers can read
• Docusaurus — full docs framework; Markdoc is a content layer that plugs into any framework
• Contentlayer — type-safe content SDK; Markdoc focuses on authoring and validation
• remark/rehype — low-level AST plugins; Markdoc provides a higher-level schema abstraction
• AsciiDoc — rich document format; Markdoc stays closer to Markdown simplicity

FAQ

Q: Is Markdoc compatible with standard Markdown? A: Yes. Any valid Markdown file is valid Markdoc. The custom tag syntax is additive.

Q: Can non-technical writers use it? A: Yes. The tag syntax is designed to be readable and writable by content authors without JavaScript knowledge.

Q: Does it work with frameworks other than Next.js? A: Yes. The core library is framework-agnostic. The Next.js plugin is a convenience wrapper.

Q: How does validation work? A: Schemas define allowed attributes, required children, and type constraints. The transform step reports errors for any violations.

Sources

• https://github.com/markdoc/markdoc
• https://markdoc.dev