A Hypermedia link is an hm:// URL. When one page links another, the linked page can show who links to it. A link to a person is a mention, and it reaches that person. All of this works because a node indexes every link it sees.
Links appear in several places: in a block as the block's link, in inline annotations, in embeds, in comment bodies and in metadata attributes. The index gives each resource its backlinks: the list of links that point at it. This page covers the index and what is built on it.
Citations and backlinks
A citation is one indexed link. Every hm:// link the daemon meets while indexing becomes a link record from the source blob to the target resource. The link can sit in a document block, an annotation, or a comment body.
The record is tagged with the source block, the fragment and the version.
A link with a pinned version is marked as exact. A link that follows the latest marks its version as a suggested minimum.
ListCitations on a target returns these records as citations, ordered by when the citing blob arrived locally. The order ignores the time the blob claims. So an old blob that arrives late can never hide a newer citation on the next page.
Four links from one version count as four citations.
For a comment citation, sourceDocument is the document the comment was written on (its target at write time). It is not the document the comment links to. So a comment elsewhere that mentions a page shows up among that page's connections, grouped under its own document.
The ListEntityMentions call is deprecated. Use ListCitations.
Block citations
A link with a block fragment cites that block. A block comment quotes its target this way, so it shows up as a citation of the block. A block's citation count is one per citing block. So a paper that cites one bibliography entry from four paragraphs shows 4 on that entry. A citation of a block records the revision it saw, so a reader can tell whether the cited text has changed since.
Mentions
A mention is an inline embed that names a person or a page. It is an Embed annotation over a placeholder character in a block's text. Its mentionKind is account or document, and its link points at the person or the page. Documents and comments use the same mechanism, described in Blocks.
The daemon indexes the mention as a link from the document or comment to the account or page it names. This link drives "mentions of me" and the mention trigger of a Seed Agent. The MentionCandidates request ranks who or what to suggest while you type.
How to write one in markdown. In the markdown that the CLI and Seed Agents read and write, a mention is a Markdown link whose label is @:
[@](hm://ACCOUNT_UID/:profile) for a person.
[@](hm://UID/path) for a document.
Any text after the @ is ignored. So the [@Name](…) form that resolved markdown prints parses back to the same mention.
The autolink <hm://ACCOUNT_UID/:profile> is equivalent.
What does not count. These are not mentions. They notify nobody and activate no agent:
a link whose label does not start with @,
a link to one of the person's comments,
plain @Name text.
Attributes. A document attribute set to a person, such as owner: hm://ACCOUNT_UID, is a mention. A bare account id or a :profile URL works too. The daemon indexes it as a metadata/Link citation anchored at the key; see Metadata.
Working with links
On the Seed API:
ListCitations returns every link record that points at a resource.
ListCommentsByReference returns comments elsewhere that quote or link a document.
InteractionSummary counts comments and citations per document and per block.
Seed Agents fire on a user-mention trigger.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime