Use <Only> to author content for one output format. Shared material stays outside the blocks; a block can contain an instruction, explanation, example, or link that serves only one version:
Shared setup steps appear in both formats.
<Only format="html">
Choose a tab below to inspect a response.
</Only>
<Only format="markdown">
The response examples follow as labeled sections.
</Only>
The example below is live. This HTML page shows the first sentence; its Markdown twin shows the second.
The same mechanism can hold a larger section. An HTML section might teach through a visual walkthrough. Its Markdown counterpart can provide file paths and a command sequence for an agent. Each version should give its reader enough to complete the task, and shared product facts should stay consistent.
This sentence appears only on the HTML page.
HTML, Markdown, and agents
An agent that fetches the direct .md URL, or requests this page with Accept: text/markdown on a host that supports content negotiation, receives the shared text and format="markdown" blocks. It does not receive format="html" blocks. For the live example above, the relevant Markdown line is:
This sentence appears only in the Markdown twin.
The build validates the contents of both blocks, including their links and supported components. <Only> needs block content and exactly one literal format attribute: html or markdown. Dynamic expressions and other values fail the build.
Keep facts, warnings, and task steps that both readers need outside <Only>, or provide suitable versions in both formats. You can add or suppress content in either output when that helps its intended reader. Check that each version remains accurate and usable for its task; see Shoalrun's position on shared and format-specific content. The browser search index uses the HTML output, so Markdown-only text is not included in that search. See publishing and agent representations for the full output contract.