Markdown

MDX19.3k★

MDX lets you put React components inside Markdown. Write prose in Markdown, drop in an interactive chart, a live code editor, or a custom callout box — all in the same file. It's the bridge between content and code that documentation sites and blogs have been waiting for. If you're building docs, a blog, or a content-heavy site with Next.js or Astro, MDX lets your content do more than static text. Regular Markdown is the baseline — universal but limited. Markdoc (Stripe) offers similar extensibility with a different syntax. AsciiDoc is powerful but niche. Contentlayer was great for typed content but is abandoned. Best for developer-focused sites where content needs interactive elements — documentation with live examples, blog posts with embedded demos, landing pages with dynamic components. The catch: MDX adds build complexity. Error messages when your JSX is malformed inside Markdown are confusing. Performance can suffer with heavy components in content. And your content is no longer portable — MDX files only work in MDX-compatible systems, unlike plain Markdown that works everywhere.

Markdoc7.9k★

Markdoc is Stripe's answer to "MDX is too powerful for its own good." A Markdown-based authoring framework where content stays declarative — no arbitrary JavaScript in your docs. Custom tags and annotations let you embed React components, but with validation and type checking that catches broken docs at build time. MDX is the main alternative — more flexible but lets content authors write arbitrary code, which is a security and maintenance headache. Contentlayer was great but got abandoned. For commercial, Readme.com and GitBook handle docs hosting. Use Markdoc if you're building documentation for a developer product and want non-engineers to contribute safely. The build-time validation is the killer feature — broken tags become build errors, not 404s. Stripe's own docs prove it scales. The catch: small community. Stripe built it for Stripe and open-sourced it, but adoption has been modest. The ecosystem of plugins, themes, and integrations is thin compared to MDX. If you leave the happy path, you're mostly on your own reading source code.