---
title: "A Busy Developer's Guide to Universal Mentions"
date: "2026-06-14T15:07:53.426Z"
updated: "2026-06-14T22:21:59.784Z"
author: "JY"
summary: "A Busy Developer's Guide to Universal Mentions Universal Mentions let social readers recognize links to people, blogs, andpublications, then offer a profile..."
---
# A Busy Developer's Guide to Universal Mentions
[Universal Mentions](https://dev.blogwarp.com/2026/05/universal-mentions-for-the-social-web/) 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:
```html
Hello @Alice
```
At `https://alice.example.com/`, the page advertises its feed with one line
inside its HTML ``:
```html
```
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:
1. Type `@`.
2. Pick someone from an autocomplete list.
3. 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:
```html
@Alice
```
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.
```html
@Alice@Alice from the garden blog
```
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:
```html
@Alice
```
it may:
1. Fetch `https://alice.example.com/`.
2. Look for RSS, Atom, or JSON Feed autodiscovery links.
3. Fetch a discovered feed and read its metadata.
4. Show a local profile card with the site's name, avatar, and recent posts.
5. 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:
```js
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:
```text
@Bo
```
The editor might suggest Bob and insert:
```html
@Bob
```
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:
```html
@Alice@Alice's notes@Alice's photos
```
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 `` tag inside the page's HTML ``:
```html
```
Atom and JSON Feed autodiscovery work too:
```html
```
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:
```html
Alice
```
Universal Mentions solve a narrower authoring and reader-UX problem by using
the familiar `@` convention. Software may support both:
```html
@Alice
```
## 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.