Markdoc tags

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

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.

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.
• Replay OpenAPI: Add the Replay console to make API calls directly from a documentation page.
• Tabs: Organize content variants into switchable tabs.

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 %}

• Markdoc tag library: Explore Markdoc tags and their rendered examples
• Create code walkthrough: Follow the tutorial to add code walkthroughs to your project