Markdoc is a Markdown-based document format and a framework for content publishing. It was designed internally at Stripe to meet the needs of our user-facing product documentation. Markdoc extends Markdown with a custom syntax for tags and annotations, providing a way to tailor content to individual users and introduce interactive elements.
1 Like
Stripe open sourced Markdoc four months ago. There is a Hacker News discussion on it from that day that includes comments by Stripe developers.
Relationship with CommonMark
From the Markdoc FAQ:
Markdoc’s syntax is largely a superset of the CommonMark specification. Markdoc introduces its own syntactic extensions, which include tags, annotations, and variable interpolation. Markdoc also supports GitHub-flavored tables, though we encourage you to use Markdoc’s own list-style tables instead.
Where it is not a superset:
- Doesn’t support Setext
- Optionally supports arbitrary indentation “to improve the readability of documents with complex structure” (enabling this disabled indented code blocks)
They expect to deviate further from CommonMark down the road:
In the future, we may create a distinct dialect of Markdown that deviates further from the CommonMark specification, removing additional features like the angle-bracket block quote syntax that can be replaced by Markdoc tags. We think there’s an opportunity to create a Markdown variant specifically for Markdoc that is less ambiguous, more prescriptive, and more conducive to rigorous specification. This would be available alongside the CommonMark-aligned syntax that we support today, giving users the option to choose whether they want a cleaner syntax or compatibility with existing Markdown tools and content.
In short, Markdoc extensions to Commonmark ignore the spirit of Markdown and are just a wrapper for HTML elements and attributes inside uniform {% … %} brackets.
Everything has already been done elsewhere, but better.
1 Like