Highlights

1 Overview

Readers underline the good parts of a book. This NIP brings that gesture to Nostr. It defines kind:9802, the highlight event. A highlight signals content a user finds valuable.

The highlighted material does not need to live on Nostr. A highlight can point to a nostr event with e or a tags. It can also point to any URL with an r tag. Reading clients can then show the passage, credit the original authors, and link back to the source.

A highlight is a regular event under NIP-01 rules. Relays store all highlights. This NIP is draft and optional: no client or relay must implement it.

2 The Highlight Event

A highlight is an event of kind:9802. The content field carries the highlighted portion of the text, verbatim.

The content may be empty. Use an empty content for highlights of media that is not text, for example NIP-94 audio or video files.

{
  "kind": 9802,
  "content": <the highlighted text, or "" for non-text media>,
  "tags": [
    ["a", <kind:pubkey:d-value>]      or ["e", <event-id>] or ["r", <url>]
    ["p", <pubkey-hex>, <relay-url>, "author"],
    ["context", <surrounding text, optional>],
    ["comment", <user commentary, optional>]
  ],
  ... standard NIP-01 fields ...
}

3 References: Tagging the Source

A highlight should tag the source of the highlighted material. This rule applies to nostr-native sources and to external sources.

• Use an a or e tag when the source is a nostr event.
• Use an r tag when the source is a URL.

Clean the URL before you tag it. A client that generates a highlight should make a best effort to remove trackers and other useless parts from the query string. For example, drop utm_source and similar parameters.

4 Attribution and Context

A client may add one or more p tags to a highlight. Each p tag credits an original author of the highlighted material. A role may be included as the last value of the tag, for example author or editor.

Attribution is most useful for non-nostr content. The client might still find a nostr pubkey for the author. It can prompt the user for one. It can also read a link tag on the source document, such as <link rel="me" href="nostr:nprofile1..." />. The nostr: URI scheme is defined in NIP-21.

{
  "tags": [
    ["p", <pubkey-hex>, <relay-url>, "author"],
    ["p", <pubkey-hex>, <relay-url>, "author"],
    ["p", <pubkey-hex>, <relay-url>, "editor"]
  ]
  // other fields...
}

A client may also add a context tag. Use it when the highlight is a subset of a paragraph. The tag carries the surrounding content. A reading client can then display the passage with enough context to make sense.

5 Quote Highlights

A user often wants to highlight a passage and comment on it in one step. Add a comment tag to the highlight to do this. The result is a quote highlight.

Clients must render a quote highlight like a quote repost (see NIP-18). The comment is the note. The highlight is the quoted content inside it. This rule exists to prevent one highlight action from creating two events, a highlight plus a kind:1 note. Two back-to-back notes look bad in micro-blogging clients.

Quote highlights add two marker rules:

• A p tag that mentions a user in the comment must carry a mention marker. This separates mentions from author and editor attributions.
• An r tag for a URL that appears in the comment must carry a mention marker. The source URL of the highlight must carry the source marker instead.

6 Worked Example

A user reads a NIP-23 article and highlights one sentence. The client publishes a plain highlight. Later the user highlights a web page and adds a comment, which produces a quote highlight.

→ ["EVENT", {
  "id": "7d10c5e1…",
  "pubkey": "9f3a22b1…",
  "created_at": 1749800000,
  "kind": 9802,
  "tags": [
    ["a", "30023:41fa9b76…:protocol-design", "wss://relay.example.com"],
    ["p", "41fa9b76…", "wss://relay.example.com", "author"],
    ["context", "Simple protocols survive. Complex protocols need committees, and committees need budgets."]
  ],
  "content": "Simple protocols survive.",
  "sig": "c04d11a2…"
}]
← ["OK", "7d10c5e1…", true, ""]

→ ["EVENT", {
  "id": "e2b91c07…",
  "pubkey": "9f3a22b1…",
  "created_at": 1749803600,
  "kind": 9802,
  "tags": [
    ["r", "https://example.com/essays/keys", "source"],
    ["p", "b7e2ff40…", "wss://relay.example.com", "author"],
    ["p", "c91d0e55…", "wss://relay.example.com", "mention"],
    ["r", "https://example.com/glossary", "mention"],
    ["comment", "This is what nostr:npub1eyt… keeps saying. See also https://example.com/glossary"]
  ],
  "content": "Your keys are your identity.",
  "sig": "8fa3d971…"
}]
← ["OK", "e2b91c07…", true, ""]
-- the client renders the comment as a note that quotes the highlight --

Note the markers in the second event. The highlighted page carries source. The URL and pubkey mentioned inside the comment carry mention. The article author carries author.

7 Version History

NIP-84 arrived in late 2023 after the highlighter feature shipped in the Highlighter client. Notable changes, newest first:

• 20252025-05Documented the <link rel="me"> technique for finding a nostr pubkey on an HTML document (#1897).
• 20252025-04Added quote highlights: the comment tag plus the mention and source markers (#1438).
• 2023-242023-2024Formatting passes, typo fixes, and removal of the in-file author list.
• 20232023-11Removed the positional "range" mechanism days after merge; it can return later if needed.
• Origin2023-11Pablo Fernandez proposed NIP-84 with kind 9802, references, attribution, and context (#501).

8 See Also

• NIP-01 — the base event format and the e, p, and a tags used here.
• NIP-18 — quote reposts; quote highlights must render the same way.
• NIP-23 — long-form articles, the most common nostr-native highlight source.
• NIP-94 — file metadata; highlight audio or video with an empty content.
• NIP-21 — the nostr: URI scheme used in link rel="me" attribution.