Two years of Markdoc: what we’ve learned about balancing developer and author experience
summary
Markdoc is a Markdown superset that Stripe builds and uses to power over a thousand pages of docs, released as open source and pulling about 7000 npm downloads per week. It decouples code from content with a validator, schema-defined tags, and both static and dynamic React renderers, deliberately omits no looping or variable assignment to avoid mutable state, and ships editor tooling (VS Code extension, planned language service and Monaco editor component). The rewrite takes two years and a ten‑engineer effort and is production proven.
AI-written summary · about
chapters (13)
- 0:00Introduction
- 0:35Key elements of a documentation platform
- 0:57What is a good user experience
- 8:05How do you do that
- 9:10What is Markdoc
- 10:16Why choose markdown
- 15:34Rendering
- 20:11Open Source
- 22:01Whats next
- 23:45Thank you
- 26:38How does Markdoc work
- 28:49How does it work in the real world
- 33:41Working at GitHub
related talks
42mDocumentation as an application: enabling interactive content tailored to the user
32mSwitching from Sphinx to Markdown
35mSwitching from Sphinx to Markdown
26mWhat you get when you invest Non-Docs time in Docs tools
05mMarkdown and the art of reuse
28mBeyond Skeuomorphic Markdown
48mUseful and Beautiful Developer Docs and How to Create Them
40mFrom resistance to adoption: navigating the challenges of docs-like-code