markdoc.dev

What it is

Markdoc is a Markdown-based authoring framework created and open-sourced by Stripe. It is positioned as a documentation format and content publishing framework. Built on CommonMark, it adds extended syntax such as tags, annotations, attributes, variables, and functions, making it suitable for content systems ranging from personal blogs to large-scale product documentation sites. Stripe uses it to power its public documentation and has also used it internally for thousands of documentation pages.

Core capabilities

Markdoc is designed around declarative content rather than mixing arbitrary code into documents. Its rendering pipeline consists of parse, transform, and render: text is first parsed into an AST, then transformed into a serializable renderable tree, and finally output as an HTML string or React elements. This structure is helpful for static analysis, CI validation, table-of-contents generation, and content transformation. It supports custom nodes, tags, attributes, and validation, allowing teams to define complex document structures, interactive components, conditional content, content inclusion, and variable interpolation.

Framework support and integrations

The documentation shows Markdoc being installed via npm/yarn as @markdoc/markdoc, with examples covering both CommonJS and ESM. It includes a built-in HTML renderer, static React renderer, and dynamic React renderer, and provides integration guides for HTML, React, and Next.js, as well as a Next.js plugin. The React renderer can map custom tags in Markdown to React/Preact components. For Vue, Svelte, and other frameworks, teams need to implement their own renderer.

Pricing and open source

Markdoc is clearly presented as an open-source project, and the documentation does not mention commercial pricing, paid plans, hosted services, or enterprise support. It can therefore be treated as a free open-source library, but teams that need hosting, permissions, search, versioning, or publishing pipelines will need to build these themselves or combine Markdoc with other tools.

Pros, cons, and ideal users

Its strengths are that it remains Markdown-friendly, is highly extensible, has comprehensive validation capabilities, and is backed by Stripe’s experience running documentation at scale. It is relatively friendly to both technical writers and developers. The downside is that it is not a complete documentation-site product, but more of a lower-level content framework. Beyond HTML and React, other frontend frameworks require additional development, and defining custom schemas also requires engineering capability. It is best suited to product documentation teams, developer platforms, technical content systems, and teams that want more control than standard Markdown or MDX provides.

Access from China

The documentation does not provide information about network accessibility from China, mirrors, payment methods, or related details, so china_access can only be marked as unknown. In practice, the core package comes from the npm ecosystem, and teams in China can use npm mirrors, private package caches, and self-hosted build pipelines. Alternatives to consider include MDX, Docusaurus, VuePress, VitePress, and Nextra.