Skip to content
Last updated

Markdoc tags

Plans:ProScaleEnterprise

Use Markdoc tags in your project to add rich formatting, interactivity and reuse capability to your content.

Built-in tags

The following Markdoc tags are included with the official Markdoc package:

  • Partial: Reuse content between project pages.
  • Table: Create rich tables with less syntax.
  • If and else: Add condition that must be fulfilled to render content.

Redocly tags

The following Markdoc tags are custom-made by Redocly:

  • Accordion and accordion group: Hide secondary content inside collapsible sections, and combine several of them into a single bordered list.
  • Admonition: Add color-coded banners to highlight important information.
  • Cards: Organize links in a "card" or "tile" layout.
  • Code snippet: Pull fragments code files directly into your documentation pages.
  • Code group: Organize a series of code-snippet tags into a tabbed layout.
  • Code walkthrough: Create interactive, step-by-step instructions for complex code development tasks.
    • Step: Define individual procedures of a code walkthrough.
    • Toggle: Add toggles to allow users to switch between variants of walkthrough content.
    • Input: Add input fields to code walkthroughs.
  • Connect MCP: Add a button that allows users to connect to the MCP (Model Context Protocol) server.
  • Diagram: Reference external diagram files (Mermaid, PlantUML, Excalidraw).
  • Image: Embed images into your project.
  • Icon: Render Font Awesome icons in your project.
  • Inline SVG: Render and style SVG images in your project.
  • Login button: Add a login button visible only to unauthenticated users.
  • JSON schema: Render schemas inside a pre-styled element.
  • JSON Example: Render JSON examples directly in your documentation pages.
  • Markdoc Example: Add examples of Markdoc syntax alongside the rendered element.
  • Numbered list: Present step-by-step instructions and timelines as a vertical list with numbered, icon, or dot markers.
  • OpenAPI code sample: Render sample code snippets directly in your documentation pages.
  • OpenAPI response sample: Render response examples directly in your documentation.
  • Prompt: Add an AI prompt that readers copy or open in an AI tool.
  • Replay OpenAPI: Add the Replay console to make API calls directly from a documentation page.
  • Tabs: Organize content variants into switchable tabs.
  • Visibility: Route content to humans or agents, controlling what renders on the page versus what's included in its Markdown version.

Block tags: use block form, not inline form

For block tags (for example, admonition, tabs, cards), keep opening and closing tags on separate lines with content between them. Single-line inline usage can be parsed as inline content and wrapped in <p> tags, which may lead to invalid nesting and hydration issues.

To learn more about Markdoc parsing, see the Markdoc Inline form section.

Recommended:

{% admonition type="success" name="Tip" %}
To perform these steps all at once, run the update script as a `sudo` user.
{% /admonition %}

Avoid:

{% admonition type="success" name="Tip" %}To perform these steps all at once, run the update script as a `sudo` user.{% /admonition %}

Resources

Built-in tags