The Markdown-based Authoring Framework
Markdoc is a Markdown-based syntax document, toolchain, and framework for creating custom documentation sites and content publishing.
It was built and released by Stripe, they designed it internally to meet the needs of user-facing product documentation. Markdoc also extends with a custom syntax for tags and annotations, providing a useful way to tailor content and introduce interactive elements to individual users.
Here is a sample extracted right from the official Markdoc website:
---
title: What is Markdoc?
---
# {% $markdoc.frontmatter.title %} {% #overview %}
Markdoc is a Markdown-based syntax and toolchain for creating custom documentation sites. Stripe created Markdoc to power [our public docs](http://stripe.com/docs).
{% callout type="check" %}
Markdoc is open-source—check out its [source](http://github.com/markdoc/markdoc) to see how it works.
{% /callout %}
## How is Markdoc different?
Markdoc uses a fully declarative approach to composition and flow control, where other solutions… [Read more](/docs/overview).
## Next steps
- [Install Markdoc](/docs/getting-started)
- [Explore the syntax](/docs/syntax)
How Markdoc Actually Works
Markdoc is not a full-blown templating language, which means is not meant to replace existing template engine solutions. However, it can be a fully declarative format that can be machine-readable from top to bottom since it parses to a data structure that can be traversed to support powerful static analysis, validation, and programmatic content transformation.
The Markdoc renderer interprets custom tags (in the sample above, {% $markdoc.frontmatter.title %} would be an example) and node (elements that Markdoc inherits from Markdown, more precisely the CommonMark specification) definitions by transforming the document data structure into a tree of renderable nodes that then convert into the desired output format.
Phases of Rendering
Markdoc has three phases of rendering: parse, transform, and render. Each phase operates on the output of the previous phases.
Parse
Transforms a raw string into an abstract syntax tree (AST) representing your Markdoc document. The AST contains information about your content, including where each piece of content exists within the document.
Transform
Takes an AST and transforms it into a renderable tree, a serializable intermediate representation of what will eventually be rendered. This object is useful for computing things like a table of contents or passing over the wire to your client. It also resolves variables into static, scalar values (string, boolean, object, and so on.).
Render
Takes in a renderable tree and converts it into rendered output. For html
, that means creating an HTML document with its markup as a string. For react, it means creating a React element.
Markdoc makes available an API to create your custom renderers (for instance, a Vue.js or SolidJS). It consists of a function that takes in a renderable tree as a parameter and returns the output.
The Benefits
- It’s open-source: No secrets 🤐 and community-supported. Just like when Meta released React, it can only make it better.
- Developer & writer friendly: Markdoc delivers a powerful, flexible, developer experience with an equally capable authoring experience.
- Adopt anywhere: Use Markdoc to create interactive documentation experiences, static content sites, authoring tooling, and more.
- Familiar syntax: Markdoc is a syntactic extension of Markdown, so you can keep using all the syntax and tooling you are used to.
- Extensible: Markdoc is highly customizable, from custom tags and nodes to entirely new renderers.
- Built-in validation: You can add custom validation throughout your content system, ensuring nothing breaks and your content remains consistent.
Did we get your interest? 👀 To play around (without having to install it), take a look at Sandbox and its 3 modes:
- Preview: See the render as the final result.
- Renderable tree: The bridge view between the AST and the preview.
- AST: The raw representation of the document content.
If you want to get get started faster, check out their Next.js plugin and start building your next project’s documentation with Stripe’s new gift to the community!