# Markdoc — Powerful Markdown Authoring Framework by Stripe

> A flexible, extensible Markdown-based authoring system that adds custom tags, attributes, and validation to standard Markdown for building documentation sites and content systems.

## Install

Save as a script file and run:

# Markdoc — Powerful Markdown Authoring Framework by Stripe

## Quick Use
```bash
npm install @markdoc/markdoc
# Parse and render in Node.js
node -e "
const Markdoc = require('@markdoc/markdoc');
const doc = Markdoc.parse('# Hello {% tag %}world{% /tag %}');
const content = Markdoc.transform(doc);
const html = Markdoc.renderers.html(content);
console.log(html);
"
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-cec0c5b3
Author: Script Depot