Markdoc is not what you expected, and that's a good thing
Beholding Stripe’s excellent documentation and wondering how they’ve built it is a modern technical writing trope. It’s no wonder, then, that when Stripe announced that they open sourced their documentation format and framework, Markdoc, folks would get psyched. I, too, was startled by the sudden release. After some initial doubts, I came to love their approach.
Stripe docs consist of user guides and examples spread across product sections, as well as a complete API reference, which is perhaps the most popular bit. For years, technical writers wondered how Stripe built their docs, which static-site generator they used, and so on. Since Stripe docs are not open source, it was an exercise in imagination. Until now.
Oh hi Mark
Markdoc is a framework for content publishing that uses a dialect of Markdown based on CommonMark. Framework here means that it doesn’t include a templating engine, nor a static-site generator. Those bits, which are essential to building a Stripe-like documentation experience, are not available yet. Instead, Markdoc provides renderers that take embedded data (tags and nodes) and make it ready for site generators to use.
If you were expecting to install a binary, tweak a template, and roll out a clone of Stripe docs à la MkDocs, you’ll be disappointed: Markdoc not only requires dedicated development effort to plug into existing React-based sites, but also some serious thought on how you want to organize and render your content and data. This isn’t surprising after all: tools are not what makes content great—they’re just enablers.
To build docs like Stripe, you need to invest the same amount of time, resources, and talent as Stripe has been doing. It’ll never be as simple as entering npm install stripedocs in your terminal.
Yet Another Markdown Extension
Markdoc’s authors acknowledge that while Markdown is well-known and easy to learn, it isn’t really suited for highly-structured content. The extensions they’ve added are meant to add custom content components to documentation, as well as making some things, such as variables, easier to use when creating Markdown-based documentation. Consider, for example, the simplicity of adding a flag-dependent bit of content:
{% if $flags.my_feature_flag %}
Username: {% $user.name %}
{% /if %}
They’re all welcome additions, though none is particularly new. But that’s not the point: the purpose of Markdoc is to let writers build complex documentation using almost the same features you’d find in MDX and AsciiDoc, without having to steer away from Markdown’s familiar syntax. In doing so, Markdoc gently elbows AsciiDoc and MDX off the ledge, and paves the way for the kind of standard we are all dreaming about:
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.
Markdoc feels like the right way
If you’ve ever had to edit MDX documentation in the past, you know how painful it can be. By choosing to extend Markdown, Markdoc better separates concerns and lets writers focus on content, without having to worry that much about JSX oddities. At the same time, by providing a JS framework, Markdoc preserves compatibility with the most popular frontend stacks. It’s a very small cost for something that important.
Markdoc might have gotten Markdown tables right!
{% table %}
* Heading 1
* Heading 2
---
* Row 1 Cell 1
* Row 1 Cell 2
---
* Row 2 Cell 1
* Row 2 cell 2
{% /table %}
While Markdoc doesn’t really solve any of the issues that still plague docs-as-code, it adds something very meaningful to the conversation by showing how you can create React-based docs sites that technical writers can live with. It also confirms that the secret to Stripe docs does not lie in superior tooling or magical markup variants: rather, the reason for their success must be found in the quality of their docs team, whose information architecture needs caused Markdoc to happen.
This is the kind of magic that happens when you provide enough technical resources to your technical writers and trust them to do the right thing.