Text Note References

1 Overview

Users mention other users and other posts all the time. A mention must survive as plain text, yet render as a rich link. This NIP standardizes how clients treat inline references to other events and profiles inside the content field.

The rule applies to any event whose content holds readable text. The main cases are kind:1 text notes (NIP-10) and kind:30023 long-form articles (NIP-23).

The convention is simple. The writing client puts a NIP-21 nostr: URI in the middle of the text, such as nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg. The reading client finds the URI, decodes it, and renders whatever it wants: a name, a link, a preview, or nothing.

2 Writing Mentions

When a client creates an event, it should encode each mention of a profile or an event as a NIP-21 code. Place the code inline, in the middle of the content, where the mention belongs.

3 Optional Reference Tags

Tags for the referenced things are optional. For each event reference, the client may add a NIP-18 quote tag:

["q", <event-id or event-address>, <relay-url>, <pubkey-if-a-regular-event>]

Add the tag when you want the mentioned profile to receive a notification. Add it also when you want the referenced event to count your mention as a reply. Omit it otherwise.

The same choice exists for profile mentions. A client can add a ["p", …] tag for a mentioned pubkey, as in the example in §5. A user who wants to mention someone without notifying them can tell the client to skip the p tag. The inline link still works.

Likewise for events: a user can reference a note without joining its reply thread. The client then omits the corresponding ["e", …] tag for that nostr:nevent1… URI. Clients may expose these choices to users, or stay opinionated and decide alone.

4 Reading Mentions

A reader client receives an event with nostr:… URIs in its content. It may first display the raw text as it is. Then it parses the text and augments each reference with any context it wants. Typical steps:

1. Find each nostr: URI in the content.
2. Decode the NIP-19 code. Extract the public key or event id, and any relay hints.
3. Fetch the profile or event from a local database or from relays.
4. Replace the URI with a display form: a highlighted @name, a link, or a preview box.

When a client turns a mention into a link, it picks the target itself. The link can be an internal page of the client, a NIP-21 nostr: link, or a direct link to a web client that handles the reference.

5 Worked Example: a Profile Mention

Bob writes a note in a client with search-and-autocomplete for users. The character @ triggers it. Bob types "hello @mat". The client offers mattn's profile, with a picture and a name. Bob presses enter. He now sees "hello @mattn", and @mattn is highlighted as a mention. Internally, the event looks like this:

{
  "content": "hello nostr:nprofile1qqszclxx9f5haga8sfjjrulaxncvkfekj097t6f3pu65f86rvg49ehqj6f9dh",
  "created_at": 1679790774,
  "id": "f39e9b451a73d62abc5016cffdd294b1a904e2f34536a208874fe5e22bbd47cf",
  "kind": 1,
  "pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
  "sig": "f8c8bab1b90cc3d2ae1ad999e6af8af449ad8bb4edf64807386493163e29162b5852a796a8f474d6b1001cddbaac0de4392838574f5366f03cc94cf5dfb43f4d",
  "tags": [
    [
      "p",
      "2c7cc62a697ea3a7826521f3fd34f0cb273693cbe5e9310f35449f43622a5cdc"
    ]
  ]
}

The mention could also be a nostr:npub1… URI instead. That form carries the public key alone, with no relay hints.

Bob publishes the event. Carol's client receives it. It first displays the content as raw text. Later it parses the text and finds the nostr: URI. It decodes the URI, extracts the public key and any relay hints, and fetches the profile from its database or from relays. Then it replaces the full URI with the name @mattn, linked to its internal page view for that profile.

6 Implementation Notes

The spec calls these "verbose and probably unnecessary considerations". They give clients room to differ:

• No client must implement the flow above. A client without autocomplete can let users paste raw NIP-19 codes into the text. It then prefixes each code with nostr: before it publishes the event.
• Event references work the same way. A user pastes a nevent1… code; the client turns it into a nostr:nevent1… URI. A reader client may then show the referenced note in a preview box — or show nothing at all.
• A client can pick other display procedures. A kind:1-only client that meets a kind:30023 nostr:naddr1… reference can render it as a link to some hardcoded web app that displays such events.
• Clients may let the user include or skip tags per mention. Mention mattn without a ["p", …] tag and no notification fires, but the link still augments.
• Reference a note without the matching ["e", …] tag and the reference stays out of that note's reply thread. Clients may expose these advanced choices, or stay opinionated.

7 Version History

The number 27 has lived two lives. Its first occupant was an unrelated "Multicasting" draft in 2022. The current spec arrived in 2023. Notable changes, newest first:

• 20262026-03Removed the references to note1 codes. Event mentions now point to nevent and naddr forms, which carry relay hints.
• 20252025-02Replaced the old "mention" markers with NIP-18 q tags for event references.
• 2023-242023-2024Link and typo fixes: NIP-21 links added, broken profile link repaired via njump, NIP author lists removed repo-wide.
• 20232023-03-25fiatjaf refactored the spec for simplicity and added the worked example plus the considerations list.
• 20232023-03-21arthurfranca rewrote number 27 as "Text Note References", an alternative to putting mention markers in tags.
• Origin2022-08-16Ricardo Arturo Cabral Mejía proposed "NIP-27 Multicasting" under this number. It was removed the same day; the number was later reused.

8 See Also

• NIP-01 — the base event format and the e/p tags referenced here.
• NIP-19 — the bech32 codes (npub, nprofile, nevent, naddr) that mentions embed.
• NIP-21 — the nostr: URI scheme that wraps those codes.
• NIP-18 — reposts and the q quote tag used for event references.
• NIP-10 — kind:1 notes and reply threading, where mention tags matter most.
• NIP-23 — kind:30023 long-form content, the other main home for inline references.