DOCSEARCHbyAlgolia
Submit Docs

Markdoc

website·Indexed 36 days ago

https://markdoc.dev

A Markdown-based syntax and toolchain for creating custom documentation sites. Developed by Stripe, Markdoc is a superset of the CommonMark specification that provides a framework for content publishing through a three-phase rendering pipeline: parse, transform, and render. It supports custom tags, attributes, variables, and functions, with official integrations for React, HTML, and Next.js via the @markdoc/next.js package.

Tokens
12.3K
Snippets
73
Records
90
Agent score
70%

What's inside Markdoc

  1. Overview of the Markdoc authoring framework

    Markdoc is an open-source, Markdown-based syntax and toolchain designed for creating custom documentation sites and interactive content experiences. It acts as a syntactic extension of CommonMark, allowing users to maintain familiar Markdown tooling while adding extensibility through custom tags, nodes, and renderers. It also includes built-in validation to ensure content consistency across large-scale sites.

  2. Overview of Markdoc document format

    Markdoc is a Markdown-based document format and publishing framework designed for highly-structured content. It extends standard Markdown with a custom syntax for tags and annotations, allowing for interactive elements, conditional content, and variable interpolation without allowing arbitrary code execution. It parses content into a machine-readable data structure (AST) that supports static analysis, validation, and programmatic transformation.

  3. Overview of Markdoc

    Markdoc is an open-source, Markdown-based syntax and toolchain designed for creating custom documentation sites. It was originally developed by Stripe to power their public documentation. Unlike some other solutions, Markdoc employs a fully declarative approach to composition and flow control.

  4. Overview of Markdoc

    Markdoc is an open-source, Markdown-based syntax and toolchain designed for creating custom documentation sites. It was originally developed by Stripe to power their public documentation. Unlike some other solutions, Markdoc employs a fully declarative approach to composition and flow control.

  5. Overview of Markdoc toolchain

    Markdoc is an open-source, Markdown-based syntax and toolchain designed for creating custom documentation sites. It was originally developed by Stripe to power their public documentation. Unlike some other solutions, Markdoc employs a fully declarative approach to composition and flow control.

  6. Overview of Markdoc

    Markdoc is an open-source, Markdown-based syntax and toolchain designed for creating custom documentation sites. It employs a fully declarative approach to composition and flow control, distinguishing it from other Markdown-based solutions. It was originally developed by Stripe to power their public documentation.

  7. Set up Markdoc with React and Express

    To use Markdoc with React, follow a decoupled architecture where Markdoc documents are parsed and transformed on the server, and the resulting content is rendered on the client using the React renderer. The process involves defining a schema, transforming the AST on the server, and passing that content to Markdoc.renderers.react in the browser.
    # Example workflow
npm run start:server
npm run start:client

  8. Understand Markdoc Tag syntax and composability

    Tags in Markdoc are syntactic extensions of Markdown. They are composable, meaning tags can be nested within other tags. Tags can be self-closing by ending with a / (e.g., {% tag /%}). If a tag contains no new lines, it is treated as an inline tag and automatically wrapped in a paragraph Node (rendering a <p> element by default) to comply with the CommonMark paragraph spec.
    {% if true %}
  {% callout type="note" %}Tags are composable!{% /callout %}
{% /if %}

{% image width=40 /%}  <!-- Self-closing tag -->

{% highlight %}Inline tag 1{% /highlight %} <!-- Inline tag -->

  9. Understand the Markdoc rendering pipeline

    Markdoc processes documents through three sequential phases:

    1. Parse: Converts a raw string into an Abstract Syntax Tree (AST). The AST contains the document structure and location data. You can use the walk() method on AST nodes to traverse or mutate the tree.
    2. Transform: Converts the AST into a 'renderable tree'. This is a serializable intermediate representation where variables are resolved into static scalar values. This tree is ideal for computing tables of contents or sending data to a client.
    3. Render: Converts the renderable tree into the final output format (e.g., HTML strings or React elements).

  10. Understand Markdoc syntax basics

    Markdoc is a superset of Markdown based on the CommonMark specification. It inherits standard Markdown nodes (Headers, Bold, Italic, Links, Images, Lists, Quotes, Inline code, and Code fences) and extends them with tags, annotations, and variables to allow for a highly extensible document model.

  11. Understand Markdoc's rendering architecture

    Markdoc uses a dedicated rendering architecture that transforms its internal data structure into a tree of renderable nodes. It currently provides three primary renderers:

    1. HTML string renderer: Produces standard HTML strings.
    2. Static React renderer: Transpiles documents into JavaScript code.
    3. Dynamic React renderer: Converts renderable tree nodes directly into React elements, enabling the use of React components within Markdown content (e.g., tab switchers, collapsible sections).

    Custom renderers can be implemented to support additional output formats or different client frameworks.

  12. Apply attributes to Markdown blocks using Annotations

    Annotations apply attributes to the enclosing Markdown block (treating them as attributes on the document node itself). Annotations must be used as inline nodes. For example, they are commonly used to add CSS classes to headings.
    # Heading {% .example %}