The prompt tag adds an AI prompt to a page. Readers can copy the prompt with one click or open it in an AI tool such as Cursor, Claude, or ChatGPT.
Wrap the prompt text with the prompt tag. The tag does not render Markdown inside the prompt. Readers see and copy the text exactly as you wrote it.
{% prompt title="Use numbered lists for procedures" actions=["claude", "chatgpt"] %}
Find the step-by-step procedures in this documentation project and convert each one to the numbered-list Markdoc tag.
Wrap each step in a numbered-item tag and start it with a heading.
Leave ordered lists that are not procedures as they are.
Read https://redocly.com/docs/realm/content/markdoc-tags/numbered-list first.
{% /prompt %}
If a prompt is longer than five lines, the tag displays only the first five. To see the whole prompt, readers select Show full prompt.
The prompt is for human readers. Realm excludes both the prompt text and its title from the Markdown version of the page, llms.txt, and AI search. Search includes only the title, so readers can find a prompt by its title.
Realm escapes angle brackets inside link text, such as [Array<T>](https://example.com), before it parses the page, so the copied prompt contains < and > instead.
| Attribute | Type | Description |
|---|---|---|
| title | string | Text displayed in the header of the prompt block. Search indexes the title, but not the prompt text. |
| icon | string | Icon displayed in the header. Either:
|
| actions | [string] | "Open in" actions displayed as a split button in the header. Accepts any combination of cursor, claude, and chatgpt. The first action is the main button. The remaining actions are in the dropdown menu. Default: []. |
| hidePrompt | boolean | Hides the prompt text until the reader clicks Show prompt. Default: false. |
| singleLine | boolean | Displays only the first line of the prompt, instead of the first five, until the reader selects Show full prompt. Default: false. |
| buttonOnly | boolean | Renders only a Copy prompt button, without the prompt text or title. With actions, the button becomes a split button with the actions in its menu. Default: false. |
Each Open in action opens the AI tool through a link that carries the prompt in the URL. Browsers limit the URL length. AI tools such as Cursor, Claude, and ChatGPT also limit the prompt that a link can prefill. A long prompt can arrive truncated, or the tool can reject the link. Keep prompts with actions short, or rely on Copy prompt for long prompts.
The following examples show common ways to configure the prompt block.
Display a prompt with a copy button:
{% prompt %}
Review this documentation project and list the pages where a numbered-list tag or an accordion tag would help readers.
Give one line per page: the file path, the tag, and the reason.
{% /prompt %}
Add a title and let readers open the prompt in an AI tool. The first action is the main button. The remaining actions are in the dropdown menu:
{% prompt title="Use accordions for optional content" actions=["claude", "chatgpt", "cursor"] %}
Find the <details> HTML elements and the long optional sections in this documentation project, such as extended examples, troubleshooting notes, and background information.
Replace each one with an accordion Markdoc tag and use its summary or heading as the title.
Put related accordions in one accordion-group tag.
Keep content that every reader needs outside accordions.
Read https://redocly.com/docs/realm/content/markdoc-tags/accordion first.
{% /prompt %}
Render a single Copy prompt button:
{% prompt buttonOnly=true %}
Connect to the MCP server at https://redocly.com/mcp over HTTP.
If you cannot connect on your own, give me the command or configuration to add it, and continue after I confirm.
Then use its tools to find which Markdoc tags Realm has for step-by-step procedures and for collapsible content, and show me the syntax of each one.
{% /prompt %}
Add actions to get a split button with the copy button as the main action:
{% prompt buttonOnly=true actions=["claude", "chatgpt"] %}
Connect to the MCP server at https://redocly.com/mcp over HTTP.
If you cannot connect on your own, give me the command or configuration to add it, and continue after I confirm.
Then use its tools to find which Markdoc tags Realm has for step-by-step procedures and for collapsible content, and show me the syntax of each one.
{% /prompt %}
Hide a long prompt behind a Show prompt button:
{% prompt title="Write a docs-writing skill" hidePrompt=true actions=["cursor"] %}
Read the pages in this documentation project and derive the writing rules they follow: heading style, sentence length, tone, how procedures and examples are structured, and how pages end.
Write the rules as an agent skill in @skills/writing-docs/SKILL.md.
Follow the format at https://redocly.com/docs/realm/customization/agent-skills: YAML front matter with name and description, then the rules an agent must follow when it writes or edits a page.
State when an agent must load the skill.
Keep the body under 80 lines.
{% /prompt %}
Truncate the prompt to one line until the reader expands it:
{% prompt title="Open the MCP server to anonymous readers" singleLine=true %}
In redocly.yaml of this project, set mcp.docs.publicEndpoint to true so AI tools of anonymous readers can reach the Docs MCP server at /mcp-public without a login.
Read https://redocly.com/docs/realm/config/mcp first and tell me what the endpoint exposes.
{% /prompt %}
Write self-contained prompts
Readers paste the prompt into a tool that does not see the page. Include the context the tool needs, such as the API name or the file to change.
Link the docs page of the feature
When a prompt asks the tool to use a Realm feature, add the URL of the feature's docs page to the prompt. The tool reads the page and uses the correct syntax.
- Markdoc tags - See the full list of supported Markdoc tags
- Numbered list tag - Render step-by-step procedures as a numbered rail of items
- Accordion tag - Hide optional content in collapsible sections
- Agent skills - Package task instructions that agents load on demand
- MCP configuration - Configure the Docs MCP server, including the public endpoint