How Stripe builds interactive docs with Markdoc

Ryan Paul

Markdoc delivers a good user experience without compromising the authoring experience. It enables writers to express interactivity and simple page logic without mixing code and content.

Stripe

•

Ryan Paul

•13 min read•intermediate•

--

•View Original

HTMLJavaScriptJSONNode.jsReactRubySinatraSvelteWebpack

Overview

The article discusses how Stripe developed Markdoc, a custom authoring format that enhances the interactivity and maintainability of their product documentation. By decoupling code from content, Markdoc allows technical writers to create rich, user-friendly documentation without the complexities of traditional coding methods.

What You'll Learn

1

How to use Markdoc to create interactive documentation

2

Why decoupling code and content improves documentation maintainability

3

When to implement custom tags in Markdoc for enhanced functionality

Prerequisites & Requirements

Familiarity with Markdown and basic web development concepts(optional)
Access to a JavaScript environment for testing Markdoc

Key Questions Answered

What is Markdoc and how does it improve documentation authoring?

Markdoc is a custom authoring format developed by Stripe that decouples code from content, allowing technical writers to create interactive documentation without the complexities of traditional coding. It enhances maintainability and enables the use of custom tags for advanced features while preserving the simplicity of Markdown.

How does Markdoc handle rendering for different output formats?

Markdoc includes a modular rendering system that supports multiple output formats, including React and HTML. This allows for flexibility in presenting the same content in various ways, such as in web applications or print-ready formats, enhancing the overall user experience.

What are the benefits of using React with Markdoc?

Using React with Markdoc allows for the inclusion of interactive features, such as collapsible sections and tab switchers, directly within documentation. This integration enhances the user experience by leveraging React's component-based architecture, making it easier to create dynamic content.

Technologies & Tools

Some links below are affiliate links. We may earn a commission if you make a purchase.

Authoring Format

Markdoc

Used for creating interactive and maintainable documentation.

Frontend Framework

React

Used for rendering Markdoc documents to a React virtual DOM.

Parsing Library

Markdown-it

Used as the tokenizer for Markdoc's parser.

Parser Generator

Peg.js

Used to generate parsing logic for Markdoc's custom tag syntax.

Key Actionable Insights

1
Utilize Markdoc to streamline your documentation process by separating content from code.
This separation allows writers to focus on content creation without getting bogged down by coding complexities, leading to a more efficient authoring experience.

2
Implement custom tags in Markdoc to enhance interactivity in your documentation.
By using custom tags, you can easily add features like conditionals and content inclusion, which enrich the documentation and provide a tailored experience for users.

3
Leverage the Abstract Syntax Tree (AST) capabilities of Markdoc for advanced content manipulation.
Using the AST allows for robust static analysis and automated refactoring, significantly improving the maintainability and quality of your documentation.

Common Pitfalls

1

Mixing code and content can lead to maintainability issues and complexity.

This often happens when documentation grows in size, making it difficult to manage and understand. To avoid this, use structured formats like Markdoc that separate content from code.

Related Concepts

Markdown

React

Documentation Best Practices