Inline references, links and annotations
This page is for developers who write or process instructions. It covers the inline forms an instruction can use in its prose: typed references to the people, tools and blocks it declares, citations, annotations, wiki links, embeds, footnotes and math. It shows how each one is recognized, what it is checked against, and exactly what the agent receives for it.
Typed references
A typed reference names a block or an object by its target, with a label a reader sees: :kind[label]{ref=target}. Its kind says what the target must be:
| Form | Required | Names |
|---|---|---|
:ref[…] | ref=… | Any block or object with an explicit id, of any kind |
:person[…] | ref=… | A person |
:role[…] | ref=… | A role |
:skill[…] | ref=… | A skill |
:mcp[…] | ref=… | An MCP server |
:tool[…] | ref=… | A tool |
:agent[…] | ref=… | An agent |
:service[…] | ref=… | A service |
:source[…] | ref=… | A source block |
:resource[…] | ref=… | A resource block: audio, diagram, drawing, figure, image, pdf, resource, video |
:cite[…] | ref=… | A source the back matter's sources list records, by its id |
:ref is the generic form: it names any block with an explicit id. The other kinds are shortcuts that also check the kind: :tool[…]{ref=#alex} where #alex is a person is an error, reference-kind. A reference is a pointer. It grants nothing: naming a tool doesn't give an agent access to it. See Tools, skills, agents and services.
::person{id=alex title="Alex" role=owner}
::mcp{id=calendar title="Calendar" server="https://calendar.example.org/mcp"}
:::policy{id=privacy title="Calendar privacy"}
NEVER: reveal a private event to another person.
:::
MUST: ask :person[Alex]{ref=#alex} before you move a confirmed meeting in :mcp[the calendar]{ref=#calendar}.
Follow :ref[the privacy policy]{ref=#privacy}, as :cite[the handbook]{ref=handbook} says.[^why] Press :kbd[Ctrl+Enter] to send.
See [[./team.md#id=privacy|the team's privacy policy]].
[^why]: Calendars hold other people's plans.
---
sources:
- { id: handbook, title: "Team handbook", uri: "https://example.org/handbook" } The label is required. It can hold emphasis and code. Keep links and other inline forms out of it: the specification doesn't allow them there, and the reader doesn't report them. A bracket in a label is balanced, or escaped as \]. Besides ref, a reference takes id, class and style, and x-… attributes, which have no effect. Any other attribute is invalid-attributes.
Targets
A ref is one of:
#id: an explicit id in this document: a block'sid, a rule'sMUST[id]:, or a heading's{#id}.#alias/id: an id in an included or inherited document, qualified by its alias. See Ids in a composed document.- A key of the front matter's
referencesmapping. - A relative or absolute URI.
Only a local #id is checked. A reference to a missing #id is a warning, reference-optional, and reads [unresolved] in the agent's text. A URI or a named reference is not fetched or checked.
:cite[label]{ref=…} names a source by the id it has in the back matter's sources list. An id the list doesn't have is a warning. See Front matter, notes and comments.
Plain mentions and tags
@alex and #planning in prose are plain text. They resolve nothing, and the agent receives them as written. The editor suggests typed references when you type @, &, # or $. See References and parameters.
Annotations
An annotation marks up its label. Its plain-text form is the label, and it adds no instruction:
| Form | Required | Meaning |
|---|---|---|
:mark[…] | — | Highlighted text |
:sub[…] | — | Subscript |
:sup[…] | — | Superscript |
:kbd[…] | — | A key or a key sequence |
:icon[…] | — | An icon, by a readable name |
:badge[…] | — | A visible status label. It changes no state |
:abbr[…] | title=… | An abbreviation; title is its expansion |
:button[…] | href=… | A link drawn as a button; href is where it goes. It never calls anything |
A required value must not be empty. Each takes id, class and style too.
Where inline forms are recognized
An inline form is read only in parsed prose: paragraphs, headings, list items, quotes and table cells. Code spans, escapes, link destinations and raw HTML come first, so nothing inside them is a reference.
- The colon must follow the start of a line, a space, or one of
([{<"'.H:sub[2]Ois text, because the colon follows a letter. - A kind is lower case:
[a-z][a-z0-9-]*, oralias:kindfor an extension's. - The label is on one line, with balanced brackets.
- The attributes follow the label at once, on the same line:
{…}. A quoted value may hold a brace. \:person[Alex]is text.
Nothing is read inside an example, a verbatim body, a YAML or JSON body, code, math or comments.
Wiki links and embeds
[[target|label]] is a navigation link. [[target]] uses the target as its label. The first pipe that isn't escaped separates the two, and \| is a literal pipe. A target is a path, a URI, #id, or a key of the front matter's references. It may select a part: [[./team.md#id=privacy|Privacy]].
![[target|label]] is an embed: a preview of the resource in place, as ::embed{src=…} is.
- A link is not an existence assertion: it is never checked, and links may form cycles.
- An embed imports nothing: the target's rules and ids don't join the document. To bring guidance in, use
::include. See Includes, inheritance and extensions. [[x]](url)is an ordinary link whose text is[x].- Inside a table cell, escape the separator pipe once more:
[[./team.md\|Team]].
The renderer draws a link as a link. It draws an embed of an image as the image when images are allowed, and any other embed as a labelled link.
Footnotes
[^label] refers to a footnote. A definition starts a line, with up to three spaces before it: [^label]: text. Its continuation lines are indented by at least four spaces. A label starts with a letter or a digit, and may contain ., _ and -. Labels are case-sensitive.
A reference without a definition is a warning, footnote-missing, and stays as text. Two definitions of one label are an error, footnote-duplicate. The renderer numbers notes in the order of their first reference.
Math
$formula$ is inline math, on one line. The opening $ is followed by a character that is not a space, a digit or another $, and the closing $ follows a character that is not a space and is not followed by a digit. So $5 or $10 stays text. A math code fence is a display formula. Nothing inside inline math or a code fence is a reference or a parameter.
This reader doesn't recognize $$ display regions. Between two $$ lines, references and ${name} are read as they are in prose. Write a display formula as a math fence.
Heading anchors and ids
A heading gets a generated anchor, and may have an explicit id: ## Morning plan {#morning-plan}. An explicit id joins the document's ids, which are unique across every kind. A generated anchor is the heading's visible text in lower case, with each run of spaces as -, and only letters, numbers, _ and - kept. A heading with nothing left is section, and a repeated anchor gets -2, -3… in order:
| Heading | Anchor |
|---|---|
| An instruction's address | an-instructions-address |
| Calendar privacy | calendar-privacy |
| Étapes du matin | étapes-du-matin |
| Step 2: review | step-2-review |
| !!! | section |
A typed reference names only explicit ids. A fragment, such as #privacy in an include's src, tries an explicit id first, then a generated anchor.
What the agent receives
Inline forms are rewritten in the agent's text (instruction-text/1) only where they are prose. The example above, delivered:
### person: Alex
Attributes: {"role":"owner"}
### mcp: Calendar
Attributes: {"server":"https://calendar.example.org/mcp"}
### Policy: Calendar privacy
NEVER: reveal a private event to another person.
MUST: ask Alex (person; #alex) before you move a confirmed meeting in the calendar (mcp; #calendar).
Follow the privacy policy (ref; #privacy), as the handbook (cite; handbook) says.[^why] Press Ctrl+Enter to send.
See [[./team.md#id=privacy|the team's privacy policy]].
[^why]: Calendars hold other people's plans. Each form, as written and as the agent receives it:
| Written | Delivered |
|---|---|
:person[Alex]{ref=#alex} | Alex (person; #alex) |
:mcp[the calendar]{ref=#calendar} | the calendar (mcp; #calendar) |
:ref[the privacy policy]{ref=#privacy} | the privacy policy (ref; #privacy) |
:cite[the handbook]{ref=handbook} | the handbook (cite; handbook) |
:tool[Search]{ref="https://tools.example.org/search"} | Search (tool; https://tools.example.org/search) |
:person[Sam]{ref=#sam} | Sam (person; #sam) [unresolved] |
:person[Alex] | :person[Alex] |
:mark[Important] | Important |
:kbd[Ctrl+Enter] | Ctrl+Enter |
:abbr[MCP]{title="Model Context Protocol"} | MCP |
:button[Read the policy]{href="./policy.md"} | Read the policy |
[[./team.md#id=privacy|the team's privacy policy]] | [[./team.md#id=privacy|the team's privacy policy]] |
![[./brief.pdf|The brief]] | ![[./brief.pdf|The brief]] |
Tentative stays tentative.[^tentative] | Tentative stays tentative.[^tentative] |
The area is $\pi r^2$. | The area is $\pi r^2$. |
`:person[Alex]{ref=#alex}` | `:person[Alex]{ref=#alex}` |
- A typed reference or a citation reads as its label, then
(kind; target). - A reference to a local
#id, or to#alias/idin a composed document, that names nothing adds[unresolved]. - A reference without
refstays as written. - An annotation reads as its label.
titleandhrefare not delivered. - Wiki links, embeds, footnotes and math are delivered as written.
- A parameter in a label is filled in. See Parameters.
The resolver binds no lookup adapters, so it adds no ### Resolved references section. The whole text profile is on What an agent receives.
If it doesn't work
Ask :person[Sam]{ref=#sam}.
Use :tool[Alex]{ref=#alex}.
Open :widget[the panel].
Ask :person[]{ref=#alex}.
Ask :person[Alex].
Per :cite[the guide]{ref=guide}.
See the note.[^missing] line 9: :person[…]: nothing in this document has the id "sam" [reference-optional]
line 10: :tool[…] names #alex, which is a person, not a tool [reference-kind]
line 11: :widget[…] is not an inline kind of this specification; it is kept as written [unknown-kind]
line 12: :person[…]: its label is required, the text a reader sees [invalid-attributes]
line 13: :person[…] needs ref=… [invalid-attributes]
line 14: :cite[…]: the backmatter's sources record no "guide" [reference-optional]
line 15: the footnote [^missing] has no definition, so it stays as text [footnote-missing] | What you see | Why | What to do |
|---|---|---|
nothing in this document has the id "…" [reference-optional] |
The #id is missing, misspelled, or in a composed document |
Add the id, or write #alias/id |
… names #…, which is a person, not a tool [reference-kind] |
The shortcut's kind isn't the target's | Use the target's kind, or :ref |
… is not an inline kind of this specification [unknown-kind] |
The kind doesn't exist | Use a kind from the tables above, or declare an extension |
its label is required, the text a reader sees [invalid-attributes] |
The label is empty | Write the label |
… needs ref=… [invalid-attributes] |
A reference without its required attribute | Add ref, or href or title for button and abbr |
the backmatter's sources record no "…" [reference-optional] |
A citation of an unlisted source | Add it to sources in the back matter |
the footnote [^…] has no definition [footnote-missing] |
A footnote without its definition | Add [^label]: … |
the extension alias "…" is not declared [extension-unavailable] |
alias:kind without the alias in extensions |
Declare the extension. See Extensions |
Every code is on Diagnostics and fixes. Still stuck: Support.