Markdoc: A Markdown-based document format and framework from Stripe

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.

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