Rules and blocks
This page is for developers who write or generate instruction documents. It lists every rule keyword and every block kind of the first edition (instruction/1): how each is written, the attributes it takes, and the exact text an agent receives from it. The tables are read from the specification's registry and the samples are delivered by the language service when this page is built, so they match what instruction deliver and spec_deliver give you.
Rule keywords
A rule is a line that starts with a keyword and a colon. These are every keyword the reader knows, and the kind each one reads as:
| Keyword | Reads as | Flag | Rule | Meaning |
|---|---|---|---|---|
MUST: | must | yes | A binding obligation within its scope. | |
MUST NOT: | never | yes | A binding prohibition. | |
NEVER: | never | yes | A binding prohibition. | |
ALWAYS: | must | yes | A binding obligation within its scope. | |
SHOULD: | should | yes | A recommended default; a departure should be explained. With not=true, a recommended avoidance. | |
SHOULD NOT: | should | not=true | yes | A recommended default; a departure should be explained. With not=true, a recommended avoidance. |
AVOID: | should | not=true | yes | A recommended default; a departure should be explained. With not=true, a recommended avoidance. |
MAY: | may | yes | A permission in the guidance. It grants no host capability. | |
GUARDRAIL: | guardrail | yes | An explicit high-importance boundary, for review and for the agent. | |
NOTE: | note | advisory | Context or advice, with no rule strength. | |
INFO: | note | advisory | Context or advice, with no rule strength. | |
TIP: | tip | advisory | Context or advice, with no rule strength. | |
IMPORTANT: | important | advisory | Context or advice, with no rule strength. | |
WARNING: | warning | advisory | Context or advice, with no rule strength. | |
CAUTION: | caution | advisory | Context or advice, with no rule strength. |
The block kinds always, avoid and info are aliases: always reads as must, avoid reads as should with not=true, info reads as note. Keywords are upper case and matched exactly; Must: or must: is ordinary text.
The operative rules are must, should, may, never and guardrail. The advisories (note, tip, important, warning, caution) carry context with no rule strength. A rule is guidance to the agent: nothing enforces it at run time, and styling a guardrail doesn't make it a control.
Writing a rule
The same rule can be written several ways. Each line below is a rule:
MUST[greet]: greet the customer by name.
**SHOULD:** answer in the customer's language.
- NEVER: promise a delivery date.
- MAY: offer a discount code when a delivery is late.
NEVER (if the customer is under 18): ask for payment details.
BECAUSE: Acme does not take payments from minors.
> [!WARNING]
> The order system is read-only on Sundays.
:::must{id=refund-method if="the order was paid by card" because="the bank reverses card payments only"}
Refund to the original card.
::: An agent receives each in its canonical form:
MUST: greet the customer by name.
SHOULD: answer in the customer's language.
NEVER: promise a delivery date.
MAY: offer a discount code when a delivery is late.
NEVER (if the customer is under 18): ask for payment details.
BECAUSE: Acme does not take payments from minors.
### warning: warning
The order system is read-only on Sundays.
MUST (if the order was paid by card): Refund to the original card.
BECAUSE: the bank reverses card payments only - A line.
KEYWORD: text, at the start of a paragraph, with at least one space after the colon. The text runs on until a blank line or a line that starts something else. - Emphasized.
**MUST:** text, with matched**markers. An unmatched marker makes no rule. - A list item or a quoted line.
- NEVER: textor> MUST: text. Each item is its own rule, and the list marker isn't delivered. - An alert. A blockquote that starts with
> [!KEYWORD]on its own line, case-insensitive, multiword keywords included (> [!MUST NOT]). An alert type that isn't a keyword stays an ordinary blockquote. - A container.
:::must{if="…" because="…"} … :::, for a rule whose body has several paragraphs or blocks.
A keyword line interrupts the rule before it, so consecutive rule lines are separate rules without blank lines between them. A line that is not a keyword continues the rule above it. A keyword in the middle of a sentence, in a heading, in a table cell, in code or inside an example is not a rule.
Rule ids
MUST[confirm]: text names a rule confirm. The id grammar is letters, digits, ., _ and -, starting with a letter or digit. A rule id shares the document's id namespace with every block id and heading {#id}, and a repeated one is duplicate-id. An id is how an extending document targets an inherited rule (Includes, inheritance and extensions).
Conditions
NEVER (if the customer is under 18): text gives a rule a condition. There is exactly one space before (if, and the condition is one line of text without parentheses. In a container, write if="…".
The condition is delivered with the rule and interpreted by the agent. The resolver never evaluates it, so every rule reaches the agent whatever its condition. An empty condition, or a condition on an advisory (NOTE (if …):), is an invalid-attributes error.
Reasons
A BECAUSE: line right after a rule, in the same block, is that rule's reason. Blank lines and comments may come between them. because="…" on a container is the same. The reason is delivered on the line after its rule.
Two reasons for one rule are an error:
MUST: refund to the original payment method.
BECAUSE: the bank reverses card payments only.
BECAUSE: it is the law. INVALID refunds.md
line 3: this rule already has a reason: give it one BECAUSE [reason-repeated] A reason with no rule before it stays prose, with a warning:
Refunds take three to five working days.
BECAUSE: the bank needs that long. ok refunds.md
warning line 3: BECAUSE: follows no rule here, so it stays prose: put it right after the rule it explains [orphan-reason] A BECAUSE: line right after an advisory keyword line (NOTE:, TIP: and the others) is kept as that advisory's because attribute, with no warning, and is delivered on its Attributes: line rather than as a reason.
Directives
Every other block is a directive, written at the start of a line:
- A container,
:::kind{attributes}, its body on the following lines and a closing line of colons. The opener and the closing line hold nothing else. - A leaf,
::kind{attributes}on one line, for a block its attributes describe completely. - An inline object,
:kind[label]{attributes}in prose. Those are on Inline references, links and annotations.
A container inside another uses fewer colons than its parent: ::::columns holds :::column. A container opened with as many colons as its parent, or closed with fewer than it opened with, is invalid-nesting. A container with no closing line is unclosed-directive: the end of the file doesn't close it.
A directive is recognized only at physical column zero, outside code, comments and HTML blocks. An indented one, or one in a list item or a blockquote, is ordinary text. A directive interrupts a paragraph and ends the list or quote around it.
:::kind words (words where the attribute list goes) is ordinary text. A well-formed directive of a kind this edition doesn't define is an unknown-kind error; it is kept as written and its body isn't read. A kind with an extension prefix, such as charts:metric, needs the alias charts in the front matter's extensions (Front matter), or it is extension-unavailable.
Attributes
An attribute list is one line between braces, right after the kind:
:::context{id=hours title="Opening hours" class="wide,muted"}
We answer from 09:00 to 17:00, Monday to Friday.
:::
:::context{#holidays .wide .muted title="Holidays"}
Closed on public holidays in Germany.
:::
:::details{open title="Why these hours" x-reviewed-by=support-leads}
Most orders arrive during the working day.
::: ### Context: Opening hours
We answer from 09:00 to 17:00, Monday to Friday.
### Context: Holidays
Closed on public holidays in Germany.
### details: Why these hours
Attributes: {"x-reviewed-by":"support-leads"}
Most orders arrive during the working day. - Values.
key=value(bare: no spaces, braces or quotes) orkey="value"(a JSON string on one line). Keys are lower case. - Shorthands.
{#hours}isid=hours, and each.wideadds toclass. A repeated key, or a shorthand plus its key, is an error. - Flags. A key alone, such as
open, istrue. A boolean takes onlytrueorfalse. - Types. An integer is
-?[0-9]+, a number may have a decimal part, and a list is a comma-separated value whose members can't be empty. Free text keeps its commas. - Unknown keys. A key the kind doesn't take is
invalid-attributes. A key startingx-is kept as an annotation with no effect, and is delivered. - Nothing runs. No attribute value is executable. Structured data goes in a YAML or JSON body, not in an attribute.
Every kind takes these common attributes, besides its own:
| Attribute | Type | Meaning |
|---|---|---|
id | id | The block's identity, unique in the document whatever its kind. `{#x}` is the same. |
title | string, one line | A display name, on one line. Generated headings in the delivered text use it. |
class | list | Presentation classes. `{.a .b}` adds to it. Never delivered. |
format | one of markdown | yaml | json | csv | text | html | code | The body's format, where the kind takes more than one. |
verbatim | boolean | Keeps a Markdown body literal: no rules, references or parameters are read in it. |
src | string | Where the object or resource is: a relative or absolute URI. |
ref | string | A reference target: a URI, a local #id, an included #alias/id or a named reference. |
mode | one of live | pinned | live (the default) reads the target when resolving; pinned needs sha256. |
version | string | A version label of the target. A label, never a pin. |
sha256 | sha256:<64 hex> | The digest a pinned reference must match. |
required | boolean | A missing target is an error instead of a partial result. |
description | string | A short description of the object. |
style | string | A presentation token, never inline CSS. Never delivered. |
In the delivered text, a block's id, title, class and style are left off its attribute line, and its title becomes its heading; a layout block also leaves off class, style, count, columns, span, open. A rule has no heading: it leaves off id, class and style, its if, because and not are in its label and reason, and a title on a rule stays on its attribute line. Every other attribute is delivered as one Attributes: line of canonical JSON (RFC 8785).
How a block is delivered
Each block becomes one unit of the delivered text, separated from the next by one blank line:
- A rule is its label, its condition, its text, its reason on the next line, and its attribute line, if it has one, after that.
- A policy, instruction or context is a
### Policy: Titleheading (Instruction:,Context:), its attribute line, then its children. - An example is
### Example: Title(### Counterexample:withavoid=true), then its body fenced asmarkdown, so a rule-looking line in it can't read as a rule. - Any other Markdown-bodied kind is
### kind: Title, its attribute line, then every child. An advisory written as a keyword or an alert has no title, so its heading is### note: note. - A structured kind is its heading, its attribute line, then its body fenced with its format.
- An allowance is stated in one fixed sentence before its body (Allowances and wallets).
A heading's title is the block's title, else its id, else its kind. Layout never hides content: every tab, column, step and closed detail is delivered, in source order. The whole profile, with the resolved references and composition changes that follow the body, is on What an agent receives.
Every kind follows, family by family. Each row's example is checked and delivered when this page is built. spec_validate and instructions_validate list the capabilities a document needs as requires: the family of every kind it uses, plus agents for an agent with no protocol, src or endpoint (one the host runs) and spending for an allowance.
Guidance
Rules, and the blocks that group or name guidance. Each rule kind is written as a keyword, an alert or a container (above). A policy keeps each rule inside it a separate rule with its origin.
| Kind | Written as | Body | Its own attributes | What it is |
|---|---|---|---|---|
alwaysalias of must | :::always, keyword, alert | Markdown | if: string, because: string | An alias of must.Example and what the agent receivesCode Delivered: Code |
avoidalias of should | :::avoid, keyword, alert | Markdown | if: string, because: string | An alias of should with not=true.Example and what the agent receivesCode Delivered: Code |
context | :::context | Markdown | none | Labelled reference material: what the agent should know, not what it must do.Example and what the agent receivesCode Delivered: Code |
guardrail | :::guardrail, keyword, alert | Markdown | if: string, because: string | An explicit high-importance boundary. Styling it enforces nothing.Example and what the agent receivesCode Delivered: Code |
instruction | :::instruction | Markdown | none | A named, reusable block of guidance.Example and what the agent receivesCode Delivered: Code |
may | :::may, keyword, alert | Markdown | if: string, because: string | A permission in the guidance. It grants no host capability.Example and what the agent receivesCode Delivered: Code |
must | :::must, keyword, alert | Markdown | if: string, because: string | A binding obligation. MUST and ALWAYS read as it.Example and what the agent receivesCode Delivered: Code |
never | :::never, keyword, alert | Markdown | if: string, because: string | A binding prohibition. MUST NOT and NEVER read as it.Example and what the agent receivesCode Delivered: Code |
policy | :::policy | Markdown | scope: string, authority: string, source: string | Groups related rules under a title, with an optional scope, authority and source. Each rule inside stays a rule.Example and what the agent receivesCode Delivered: Code |
should | :::should, keyword, alert | Markdown | if: string, because: string, not: boolean | A recommended default; with not=true (SHOULD NOT), a recommended avoidance.Example and what the agent receivesCode Delivered: Code |
Advisories and examples
Labelled advice with no rule strength, and quoted examples. An example's body is base Markdown with nothing of the language read in it: no rules, references or parameters. Only its closing line is recognized. verbatim=true does the same for any Markdown-bodied block.
| Kind | Written as | Body | Its own attributes | What it is |
|---|---|---|---|---|
caution | :::caution, keyword, alert | Markdown | none | A caution, with no rule strength.Example and what the agent receivesCode Delivered: Code |
example | :::example | Markdown, quoted | avoid: boolean | Quoted material, labelled as an example; avoid=true makes it a counterexample. Its body is never read for rules, references or parameters.Example and what the agent receivesCode Delivered: Code |
important | :::important, keyword, alert | Markdown | none | Something important, with no rule strength.Example and what the agent receivesCode Delivered: Code |
infoalias of note | :::info, keyword, alert | Markdown | none | An alias of note.Example and what the agent receivesCode Delivered: Code |
note | :::note, keyword, alert | Markdown | none | A note. NOTE and INFO read as it.Example and what the agent receivesCode Delivered: Code |
tip | :::tip, keyword, alert | Markdown | none | A tip.Example and what the agent receivesCode Delivered: Code |
warning | :::warning, keyword, alert | Markdown | none | A warning, with no rule strength.Example and what the agent receivesCode Delivered: Code |
Contracts
What the agent answers with, the inputs it collects, its parameters and its terms. A value collected by a form becomes a parameter only through a declared parameter (Parameters).
| Kind | Written as | Body | Its own attributes | What it is |
|---|---|---|---|---|
form | :::form | Markdown | none | The inputs to collect. A renderer may show fields; the body stays shared.Example and what the agent receivesCode Delivered: Code |
glossary | :::glossary | Markdown | none | Terms and their definitions, as a definition list. Terms create no ids.Example and what the agent receivesCode Delivered: Code |
output | :::output | Markdown | response-format: string, schema: string | The response contract: a response-format and an optional schema reference. A schema alone doesn't promise the host validates answers.Example and what the agent receivesCode Delivered: Code |
param | ::param | none (leaf) | name (required): string, type: one of string | number | integer | boolean | enum | list | url | duration, values: list, default: any, example: any, source: one of input | workspace | identity | static, required: boolean, description: string | Declares a parameter in the body (name required), as the front matter's parameters do.Example and what the agent receivesCode Delivered: Code |
Connected objects
People, roles, skills, MCP servers, tools, agents, services, sources and wallets the guidance refers to. Declaring one grants nothing: a server's tools, allow and deny say what the author intends, and the host decides what may be connected and called. Their targets, protocols and the integrations policy are on Tools, skills, agents and services.
| Kind | Written as | Body | Its own attributes | What it is |
|---|---|---|---|---|
agent | :::agent, ::agent | Markdown | protocol: string, endpoint: string, binding: string, tenant: string, skills: list, resolver: string, account: stringid required | Another agent: an A2A agent (protocol=a2a, with src or endpoint), or one the host runs.Example and what the agent receivesCode Delivered: Code |
mcp | :::mcp, ::mcp | Markdown | registry: string, server: string, account: string, tools: list, allow: list, deny: list, resolver: string, protocol: stringid required | An MCP server: an endpoint, a registry entry or server metadata. tools, allow and deny state intended use and grant nothing.Example and what the agent receivesCode Delivered: Code |
person | :::person, ::person | Markdown | role: string, resolver: string, account: string, protocol: stringid required | A person, by a stable id and a readable label.Example and what the agent receivesCode Delivered: Code |
role | :::role, ::role | Markdown | resolver: string, account: string, protocol: stringid required | A role, which may be a different person in each deployment.Example and what the agent receivesCode Delivered: Code |
service | :::service, ::service | Markdown | resolver: string, account: string, media-type: string, protocol: stringid required | A service other than MCP, such as an OpenAPI description (protocol=openapi/3.1).Example and what the agent receivesCode Delivered: Code |
skill | :::skill, ::skill | Markdown | trigger: string, resolver: string, protocol: stringid required | An Agent Skills SKILL.md, local guidance or another instruction. Its trigger is guidance, not a condition the resolver checks.Example and what the agent receivesCode Delivered: Code |
source | :::source, ::source | Markdown | resolver: string, account: string, media-type: string, protocol: stringid required | A source of information the guidance draws on.Example and what the agent receivesCode Delivered: Code |
tool | :::tool, ::tool | Markdown | server (required): string, name (required): string, allow: list, deny: list, protocol: stringid required | One tool of a server: server=#id names the document's mcp or service, and name the tool.Example and what the agent receivesCode Delivered: Code |
wallet | :::wallet, ::wallet | Markdown | account: string, rails: list, resolver: string, protocol: stringid required | A payment instrument the host holds, by its account alias, and the rails it may be used on. It carries no card, key or token.Example and what the agent receivesCode Delivered: Code |
Authority
What an agent may spend, on what, and who approves. An allowance only narrows what the host allows, and a host applies it only when it is granted spending. See Allowances and wallets.
| Kind | Written as | Body | Its own attributes | What it is |
|---|---|---|---|---|
allowance | :::allowance | Markdown | wallet: list, currency: string, max: string, budget: string, per: string, times: string, payees: string, categories: list, from: string, until: string, approve-above: string, approver: stringid required | What an agent may spend, on what, and who approves.Example and what the agent receivesCode Delivered: Code |
Resources, media and drawings
Images, audio, video, PDFs, figures, diagrams and drawings. The Markdown body is the shared description. The specification asks an informative media block for alt text, a description or a transcript, and a decorative image for decorative=true; the reader doesn't check it. A PDF takes page (1 or more); audio and video take start and end in milliseconds, with end after start; an image takes region as x,y,width,height, fractions inside the unit square. A selector isn't a promise to extract text.
| Kind | Written as | Body | Its own attributes | What it is |
|---|---|---|---|---|
audio | :::audio, ::audio | Markdown | media-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: string | Audio, optionally a range in milliseconds (start, end).Example and what the agent receivesCode Delivered: Code |
diagram | :::diagram, ::diagram | Markdown | media-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: string | A diagram: a description, usually around a mermaid fence. A diagram is never an executable workflow.Example and what the agent receivesCode Delivered: Code |
drawing | :::drawing, ::drawing | Markdown | media-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: string | An editable drawing: its source (SVG, Excalidraw, JSON Canvas), an optional preview and a description.Example and what the agent receivesCode Delivered: Code |
figure | :::figure | Markdown | media-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: string | A figure: shared content with a caption.Example and what the agent receivesCode Delivered: Code |
image | :::image, ::image | Markdown | media-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: string | An image. An informative one has alt text or a description; a decorative one says decorative=true.Example and what the agent receivesCode Delivered: Code |
pdf | :::pdf, ::pdf | Markdown | media-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: string | A PDF, optionally one page.Example and what the agent receivesCode Delivered: Code |
resource | :::resource, ::resource | Markdown | media-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: string | Any resource, by its address and media type.Example and what the agent receivesCode Delivered: Code |
video | :::video, ::video | Markdown | media-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: string | Video, optionally a range in milliseconds (start, end).Example and what the agent receivesCode Delivered: Code |
Technical objects
Code, data, configuration, schedules, workflows, sandboxes, tests and evaluations. Structured bodies are YAML unless format says otherwise, follow the YAML rules on Front matter, notes and comments, and are delivered as fenced source. A body that doesn't parse, or isn't a mapping where one is needed, is invalid-structured-body. Nothing runs, arms or deploys when a document is read, rendered or delivered. The native workflow language is on Workflow node reference, and eval cases on Evals and tests.
| Kind | Written as | Body | Its own attributes | What it is |
|---|---|---|---|---|
config | :::config | YAML, JSON (default YAML) | dialect (required): string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>id required | Runtime configuration for an explicit compiler or export (dialect required), never extra guidance.Example and what the agent receivesCode Delivered: Code |
data | :::data | YAML, JSON, CSV, TEXT (default YAML) | schema: stringid required | Data: YAML (the default), JSON, CSV or text. CSV cells stay strings and are never evaluated.Example and what the agent receivesCode Delivered: Code |
eval | :::eval | YAML, JSON (default YAML) | dialect: string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>id required | Model cases: each a name, a message and what the answer is expected to hold. instruction eval runs those with no adapter or adapter=instruction.md/claude.Example and what the agent receivesCode Delivered: Code |
properties | :::properties | YAML, JSON (default YAML) | patch: boolean | A structured mapping attached to its parent block. A key may not repeat one of the parent's attributes, and a parent has one at most.Example and what the agent receivesCode Delivered: Code |
sandbox | :::sandbox | YAML, JSON (default YAML) | dialect: string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>id required | An execution profile for an explicit test or export adapter: data, not a runtime.Example and what the agent receivesCode Delivered: Code |
schedule | :::schedule | YAML, JSON (default YAML) | dialect (required): string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>id required | A schedule in a named dialect. Reading or rendering it arms nothing.Example and what the agent receivesCode Delivered: Code |
script | :::script | Markdown | lang: string, sandbox: string, entry: stringid required | Code with its documentation (lang, sandbox, entry). It never runs by being read.Example and what the agent receivesCode Delivered: Code |
test | :::test | YAML, JSON (default YAML) | dialect: string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>id required | Fixtures and assertions for code or workflows, for a test adapter.Example and what the agent receivesCode Delivered: Code |
workflow | :::workflow | YAML, JSON (default YAML) | dialect (required): string, adapter: string, target: string, schema: string, schema-sha256: sha256:<64 hex>id required | A workflow in a named dialect. instruction/workflow is the native one, checked against its node registry.Example and what the agent receivesCode Delivered: Code |
Layout
Sections, columns, grids, cards, tabs, steps, details and asides. A layout has no instruction authority. A column belongs in columns, a tab in tabs and a step in steps; anywhere else is invalid-nesting.
| Kind | Written as | Body | Its own attributes | What it is |
|---|---|---|---|---|
aside | :::aside | Markdown | none | Content beside the main text.Example and what the agent receivesCode Delivered: Code |
card | :::card | Markdown | none | A card, in a grid or on its own. Shown with |
columninside columns | :::column | Markdown | span: integer 1–12 | One column, inside columns (span 1–12). Shown with |
columns | :::columns | Markdown | count: integer 1–12 | Columns (count 1–12). A renderer may stack them; reading order stays.Example and what the agent receivesCode Delivered: Code |
details | :::details | Markdown | open: boolean | A disclosure (open=true shows it open). Closed or not, it is delivered.Example and what the agent receivesCode Delivered: Code |
grid | :::grid | Markdown | columns: integer 1–12 | A grid (columns 1–12) of cards.Example and what the agent receivesCode Delivered: Code |
section | :::section | Markdown | none | A titled section of content.Example and what the agent receivesCode Delivered: Code |
stepinside steps | :::step | Markdown | none | One step, inside steps. Shown with |
steps | :::steps | Markdown | none | Numbered steps.Example and what the agent receivesCode Delivered: Code |
tabinside tabs | :::tab | Markdown | none | One tab, inside tabs. Shown with |
tabs | :::tabs | Markdown | none | Tabs. A fenced code block directly inside tabs is a tab of its own. Every tab is delivered.Example and what the agent receivesCode Delivered: Code |
Presentation
A named component a renderer may draw. Its Markdown body is the fallback, shown where the component isn't installed, and is all the agent receives. A component adds no guidance beyond it.
| Kind | Written as | Body | Its own attributes | What it is |
|---|---|---|---|---|
component | :::component | Markdown | component (required): string, stylesheet: string | An installed component a renderer may draw, optionally with a stylesheet. Unknown components show the fallback.Example and what the agent receivesCode Delivered: Code |
Composition
Including other documents and patching inherited ones. The examples below are resolved over a shared fragment and a base document; their full contract is on Includes, inheritance and extensions.
| Kind | Written as | Body | Its own attributes | What it is |
|---|---|---|---|---|
embed | :::embed, ::embed | Markdown | media-type: string, alt: string, caption: string, transcript: string, preview: string, decorative: boolean, page: integer ≥ 1, start: integer ≥ 0, end: integer ≥ 0, region: stringsrc required | Shows a resource or a fragment in place, without importing its definitions.Example and what the agent receivesCode Delivered: Code |
extend | :::extend | Markdown | target (required): string, reason: string, position: one of prepend | append | Adds children before or after an inherited block's (position=append by default).Example and what the agent receivesCode Delivered: Code |
include | ::include | none (leaf) | as (required): idsrc required | Inserts another document's body or a selected part of it, under an alias (as).Example and what the agent receivesCode Delivered: Code |
remove | ::remove | none (leaf) | target (required): string, reason: string | Removes an inherited block.Example and what the agent receivesCode Delivered: Code |
replace | :::replace | Markdown, YAML, JSON (default Markdown) | target (required): string, reason: string | Replaces an inherited block by its qualified id.Example and what the agent receivesCode Delivered: Code |
Code fences
An ordinary fenced code block keeps its language and its text exactly. Nothing in it is read as the language: no rules, directives, references or parameters. A trailing attribute list on the info line takes id, title, filename, highlight (lines such as 2-3,5), caption and preview; the language is the first word.
```python {#format filename="format.py" highlight="2" caption="Keep the status visible"}
def line(event):
return f"{event['time']}: {event['title']} ({event['status']})"
```
```html {title="Reminder email"}
<p>Your 09:00 meeting is <b>tentative</b>.</p>
```
```svg {caption="Two steps"}
<svg viewBox="0 0 120 40"><rect x="2" y="2" width="50" height="36" fill="none" stroke="currentColor"/><rect x="68" y="2" width="50" height="36" fill="none" stroke="currentColor"/></svg>
``` The agent receives every fence unchanged, attribute list included:
```python {#format filename="format.py" highlight="2" caption="Keep the status visible"}
def line(event):
return f"{event['time']}: {event['title']} ({event['status']})"
```
```html {title="Reminder email"}
<p>Your 09:00 meeting is <b>tentative</b>.</p>
```
```svg {caption="Two steps"}
<svg viewBox="0 0 120 40"><rect x="2" y="2" width="50" height="36" fill="none" stroke="currentColor"/><rect x="68" y="2" width="50" height="36" fill="none" stroke="currentColor"/></svg>
``` What a reader of the rendered document sees depends on the language:
| Language | Drawn as |
|---|---|
html |
Two tabs: Rendered, the page the code describes, and Code. The page is drawn in a sandboxed frame that runs no script, submits no form, can't reach the host page or its storage, and loads only images and styles. preview=false keeps the fence as code only. |
mermaid |
A diagram, drawn when the Mermaid runtime loads. Its source shows until then. |
svg |
A drawing, reduced to shapes, paths and text (no scripts, links, styles, images or event handlers). A fence that isn't an SVG stays code. |
math |
A display formula, as its source. |
instruction |
Code. In someone else's Markdown, the renderer's script draws an instruction, instruction-md or instruction.md fence as an instruction (Embed). |
| Any other | Code. |
A diagram is a description, never a workflow: a Mermaid flowchart doesn't run. Inside tabs, a fence that isn't in a tab is a tab of its own, titled by its title, else its filename, else its language:
:::tabs{title="Install"}
```bash {title="npm"}
npm i -g instruction.md
```
```bash {title="pnpm"}
pnpm add -g instruction.md
```
::: ### tabs: Install
```bash {title="npm"}
npm i -g instruction.md
```
```bash {title="pnpm"}
pnpm add -g instruction.md
``` If a block doesn't read
| What you see | Why | What to do |
|---|---|---|
:::kind is not closed: end it with a line of ::: (unclosed-directive) |
A container has no closing line. | Add a line of as many colons as the opener. |
… opens inside a ::: container with as many colons or more (invalid-nesting) |
An inner container uses as many colons as its parent. | Give the outer one more colons: ::::columns around :::column. |
:::column belongs inside :::columns (invalid-nesting) |
A column, tab or step outside its parent. |
Put it inside columns, tabs or steps. |
"key" is not an attribute this kind takes (invalid-attributes) |
A key the kind and the common attributes don't have. | Check the kind's row above, or write it as x-key. |
::kind needs id=… (invalid-attributes) |
A required attribute is missing. | Add it. Each kind's required attributes are in its row above. |
the id "…" is used twice (duplicate-id) |
Two blocks, rules or headings share an id. | Rename one: ids are unique across the document, whatever their kind. |
NOTE is advice, not a rule: it takes no (if …) condition (invalid-attributes) |
A condition on an advisory. | Make it a rule, or write the condition in its text. |
:::kind is not a kind of this specification (unknown-kind) |
A misspelled kind, or one from Specification 1.1. | Use a kind from the tables above; Upgrade from Specification 1.1 converts old blocks. |
| A rule arrives as plain prose | The keyword is lower case, indented four spaces, in a heading or table cell, or has no space after its colon. | Start the line with the upper-case keyword, a colon and a space. |
Every code, with the fix the language service offers, is on Diagnostics and fixes. Still stuck? Ask support.