A Busy Developer's Guide to Universal Mentions

Universal Mentions let social readers recognize links to people, blogs, and
publications, then offer a profile card and one-click subscription using feed
discovery.

They use an ordinary HTML link whose target page provides standard feed
autodiscovery:

Hello <a href="https://alice.example.com/">@Alice</a>

At https://alice.example.com/, the page advertises its feed with one line
inside its HTML <head>:

<link rel="alternate" type="application/rss+xml" href="/feed.xml">

The @ link tells a social reader which links are mentions. Feed autodiscovery
lets it find the subscription associated with each mentioned site.

What problem does this solve?

On social networks, mentioning and following someone is easy:

Type @.
Pick someone from an autocomplete list.
Readers click the mention to see a profile and follow them.

The web already has links for identifying sites and feeds for subscribing to
them. What is often missing is the connection between the two.

A reader normally cannot tell whether a link points to an article, a shop, a
person, or a blog worth subscribing to. Universal Mentions give it a cheap,
human-readable hint.

The convention

A Universal Mention has two parts:

<!-- In the mentioning document -->
<a href="https://alice.example.com/">@Alice</a>

<!-- At https://alice.example.com/ -->
<link rel="alternate" type="application/rss+xml" href="/feed.xml">

The mention is an HTML link whose visible text starts with @. Its target URL
is the identity, and its visible name is only a label chosen by the author.

The target page uses RSS, Atom, or JSON Feed autodiscovery so readers can find
the associated subscription.

<a href="https://alice.example.com/">@Alice</a>
<a href="https://alice.example.com/">@Alice from the garden blog</a>

Both links mention the same site.

Universal Mentions require:

no new HTML element;
no central username directory;
no new network protocol;
no browser changes.

Software that does not support Universal Mentions treats one as an ordinary
link. If the target page does not provide feed autodiscovery, mention-aware
software also leaves it as an ordinary link because it cannot offer a
subscription.

Why use `@`?

The @ is not required to make an HTML link work. It is a convention with
useful consequences:

people already recognize it as a mention;
writing tools can use it to trigger autocomplete;
it distinguishes a social mention from an ordinary link;
readers can attempt feed discovery only for likely social identities instead
of crawling every link in every post.

It is both an authoring affordance for people and a discovery hint for
software.

Reader behavior

When a social reader encounters:

<a href="https://alice.example.com/">@Alice</a>

it may:

Fetch https://alice.example.com/.
Look for RSS, Atom, or JSON Feed autodiscovery links.
Fetch a discovered feed and read its metadata.
Show a local profile card with the site's name, avatar, and recent posts.
Offer a Subscribe button.

A reader should cache discovery results. If discovery fails, it should leave
the link alone.

A minimal implementation looks like this:

for (const link of post.querySelectorAll("a[href]")) {
  if (!link.textContent.trim().startsWith("@")) continue;

  const feed = await discoverFeed(link.href);
  if (feed) enhanceWithProfileCard(link, feed);
}

The details of the profile card are local UI decisions. Universal Mentions
only provide the signal and target URL.

Writer behavior

A writing tool may provide a local address book and mention autocomplete.

When Alice wants to mention Bob, she types:

@Bo

The editor might suggest Bob and insert:

<a href="https://bob.example.org/">@Bob</a>

The address book does not need to be global or shared. It may contain contacts
collected from the author's subscriptions, reading history, or manual entries.

Multiple identities

Universal Mentions do not assume that a person has one canonical identity.
A person may have several sites:

<a href="https://alice.example.com/">@Alice</a>
<a href="https://alice.example.org/">@Alice's notes</a>
<a href="https://photos.example.net/alice/">@Alice's photos</a>

Each link identifies its target by URL. Writing tools may label and organize
those URLs however they like.

Feed discovery

Mentioned sites need no Universal Mentions-specific endpoint. They must provide
standard feed autodiscovery at the mentioned URL. Feed autodiscovery simply
means adding a <link> tag inside the page's HTML <head>:

<link rel="alternate" type="application/rss+xml" href="/feed.xml">

Atom and JSON Feed autodiscovery work too:

<link rel="alternate" type="application/atom+xml" href="/feed.atom">
<link rel="alternate" type="application/feed+json" href="/feed.json">

Good feed metadata makes better profile cards.

Relationship with Webmention

Webmention answers:

How do I notify a page that I linked to it?

Universal Mentions answer:

How does a reader recognize a social mention and offer a profile and
subscription experience?

They are complementary and independent. A publisher may send a Webmention
after publishing a Universal Mention, but Universal Mentions do not require
notifications.

Relationship with microformats

Microformats can provide richer link semantics:

<a class="h-card" href="https://alice.example.com/">Alice</a>

Universal Mentions solve a narrower authoring and reader-UX problem by using
the familiar @ convention. Software may support both:

<a class="h-card" href="https://alice.example.com/">@Alice</a>

Relationship with ActivityPub

ActivityPub provides a protocol for federated social networking. Universal
Mentions do not.

Universal Mentions are only a convention for recognizing social links inside
ordinary HTML content. They can be used with ActivityPub, Webmention, RSS,
Atom, JSON Feed, or none of them.

Non-goals

Universal Mentions are not:

a notification system;
a global username system;
a replacement for Webmention or ActivityPub;
a new meaning for HTML links;
a requirement for generic browsers;
a plain-text mention format.

The short version

Writers create an ordinary link whose label begins with @. The target page
provides standard feed autodiscovery.

Readers may use that hint to discover the target site's feed and offer a local
profile card and Subscribe button.

Everyone else sees an ordinary link.