Skip to content

Mentions ​

Use a mention to refer to a user, discussion, or message UUID. The parser records the kind and identifier. The host supplies readable labels and destinations.

SyntaxAST kindHost adapter
<@uuid>MentionType::Userdata.mention("user", id, signal)
<#uuid>MentionType::Discussiondata.mention("discussion", id, signal)
<^uuid>MentionType::Messagedata.message(id, signal)

UUID text must have the xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx shape: hexadecimal groups of 8, 4, 4, 4, and 12 characters. UUID v7 is supported. The syntax is not limited to UUID v4. A malformed UUID does not produce a Mention node; parser recovery can retain it as ordinary text.

User mentions ​

Use <@uuid> to mention a user:

sevenmark
This feature was implemented by <@550e8400-e29b-41d4-a716-446655440000>.
Please contact <@019a0000-0000-7000-8000-000000000001> for more information.

The host adapter supplies the current display name and an optional profile URL. Parsing or rendering this syntax does not send a notification.

Discussion mentions ​

Use <#uuid> for a discussion reference:

sevenmark
See <#550e8400-e29b-41d4-a716-446655440000> for the full specification.
This is related to <#6ba7b810-9dad-11d1-80b4-00c04fd430c8>.

The AST kind is MentionType::Discussion. The host determines how the UUID resolves within its discussion or document context. SevenMark does not fetch that target.

Discussion message references ​

Use <^uuid> to retain a discussion message identity:

sevenmark
This answer follows <^019a0000-0000-7000-8000-000000000001>.

A host with the current discussion context can resolve the UUID, show its stable sequence, such as #30, and supply a message URL. Without that adapter, the renderer leaves escaped source text visible and inert.

Editors can offer ^ or ^30 completion. Stored syntax remains <^uuid>; <^30> is not a message reference. The parser does not fetch messages or check access.

Mentions in structured content ​

Mentions can appear within headings, list items, and table cells.

List ​

sevenmark
{{{#list #type="numeric"
[[Assigned to <@550e8400-e29b-41d4-a716-446655440000>]]
[[Reference: <#6ba7b810-9dad-11d1-80b4-00c04fd430c8>]]
[[Reviewed by <@f47ac10b-58cc-4372-a567-0e02b2c3d479>]]
}}}

Table ​

sevenmark
{{{#table
[[[[Task]] [[Assignee]] [[Related Doc]]]]
[[[[Feature A]] [[<@550e8400-e29b-41d4-a716-446655440000>]] [[<#6ba7b810-9dad-11d1-80b4-00c04fd430c8>]]]]
[[[[Bug Fix]] [[<@f47ac10b-58cc-4372-a567-0e02b2c3d479>]] [[<#7c9e6679-7425-40de-944b-e07fc1f90ae7>]]]]
}}}

Rendering and runtime resolution ​

The Rust renderer emits a span with data-uuid and one of these classes:

  • sm-mention-user
  • sm-mention-discussion
  • sm-mention-message

User and discussion spans wait for a host adapter to supply content. Message spans retain visible escaped source text until the adapter resolves them.

The browser runtime calls the adapter with an abort signal. The host must check current access before it returns a label or destination. The runtime inserts labels as text. It creates a link only when the adapter supplies a safe URL.

If an adapter returns null, the runtime displays labels.unknownMention, whose default is Unknown. Without an adapter, the renderer's placeholder remains. The host chooses labels and routes; SevenMark does not require every mention to be a profile or document link.

User mention analysis ​

POST /v1/analyze returns sorted, unique canonical user UUIDs in user_mentions. The analyzer evaluates local definitions and conditionals before it collects active user mentions in the host source.

Code, literal text, comments, editor notes, and inactive branches do not add notification targets. Analysis does not load included sources. A mention in included content is not attributed to the host author.

The host owns current account eligibility, visibility, deduplication, and delivery. See the renderer wire contract.