12<html lang="en">3<head>4<meta charset="utf-8">5<meta name="viewport" content="width=device-width, initial-scale=1">6<title>NIP-84 - Highlights — Nostr Instruction Manual</title>7<meta name="description" content="NIP-84: highlight events. Kind 9802 marks a valuable portion of an article, note, or URL, with source, attribution, context, and quote highlights.">8<link rel="preload" href="../assets/fonts/michroma-400-latin.woff2" as="font" type="font/woff2" crossorigin>9<link rel="preload" href="../assets/fonts/exo2-var-latin.woff2" as="font" type="font/woff2" crossorigin>10<link rel="preload" href="../assets/fonts/sairacondensed-600-latin.woff2" as="font" type="font/woff2" crossorigin>11<link rel="preload" href="../assets/fonts/sairacondensed-700-latin.woff2" as="font" type="font/woff2" crossorigin>12<link rel="preload" href="../assets/fonts/sairacondensed-500-latin.woff2" as="font" type="font/woff2" crossorigin>13<link rel="preload" href="../assets/fonts/sharetechmono-400-latin.woff2" as="font" type="font/woff2" crossorigin>14<link rel="preload" href="../assets/fonts/exo2-400i-latin.woff2" as="font" type="font/woff2" crossorigin>15<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">16<link rel="stylesheet" href="../assets/manual.css">17</head>18<body>1920<svg width="0" height="0" style="position:absolute">21 <defs>22 <marker id="arr" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto">23 <path d="M1,1 L8,4.5 L1,8 Z" fill="#f26a00"/>24 </marker>25 <marker id="arrb" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto">26 <path d="M1,1 L8,4.5 L1,8 Z" fill="#2e5f9e"/>27 </marker>28 </defs>29</svg>3031<div class="page">32 <span class="staple s1"></span><span class="staple s2"></span>3334 <header class="band">35 <a class="logo" href="../index.html">NOSTR<b>▸</b>PROTOCOL MANUAL</a>36 <span class="booklet-note">Chapter 84 - Social</span>37 </header>38 <nav class="tabs">39 <a href="../index.html">Contents</a>40 <a href="#overview" class="on">Overview</a>41 <a href="#spec">Spec</a>42 <a href="#examples">Examples</a>43 <a href="#history">History</a>44 </nav>4546 <div class="chapter">47 <div class="nipno" data-n="84">84</div>48 <div class="titles">49 <div class="kicker">Nostr Implementation Possibility - Hex № 84</div>50 <h1>Highlights</h1>51 <p class="sub">One event kind that marks the exact passage a user found valuable, in a nostr event or anywhere on the web.</p>52 </div>53 </div>5455 <main class="spread">56 <div class="main">5758 <h2 class="bar" id="overview"><span class="num">1</span> Overview</h2>59 <p>Readers underline the good parts of a book. This NIP brings that gesture to Nostr. It defines <code>kind:9802</code>, the <strong>highlight</strong> event. A highlight signals content a user finds valuable.</p>60 <p>The highlighted material does not need to live on Nostr. A highlight can point to a nostr event with <code>e</code> or <code>a</code> tags. It can also point to any URL with an <code>r</code> tag. Reading clients can then show the passage, credit the original authors, and link back to the source.</p>61 <p>A highlight is a regular event under <a href="01.html">NIP-01</a> rules. Relays store all highlights. This NIP is <code>draft</code> and <code>optional</code>: no client or relay must implement it.</p>6263 <div class="box hint">64 <span class="tag">Hint!</span>65 <p>Think of a highlight as a public marker pen. The <code>content</code> holds the marked text itself, so other clients can render the quote even when the source is offline or off-Nostr.</p>66 </div>6768 <figure class="diagram">69 <div class="frame">70 <svg viewBox="0 0 560 210" role="img" aria-label="A highlight event points at its source with e, a, or r tags and at the original authors with p tags">71 <rect class="d-actor" x="205" y="75" width="150" height="60" rx="8"/>72 <text class="d-actor-label" x="280" y="100" text-anchor="middle">Highlight</text>73 <text class="d-note" x="280" y="118" text-anchor="middle">kind 9802</text>74 <rect class="d-actor" x="10" y="20" width="130" height="46" rx="8"/>75 <text class="d-actor-label" x="75" y="41" text-anchor="middle">Nostr event</text>76 <text class="d-note" x="75" y="57" text-anchor="middle">note or article</text>77 <rect class="d-actor" x="10" y="144" width="130" height="46" rx="8"/>78 <text class="d-actor-label" x="75" y="165" text-anchor="middle">Web page</text>79 <text class="d-note" x="75" y="181" text-anchor="middle">https://…</text>80 <rect class="d-actor" x="420" y="82" width="130" height="46" rx="8"/>81 <text class="d-actor-label" x="485" y="103" text-anchor="middle">Authors</text>82 <text class="d-note" x="485" y="119" text-anchor="middle">pubkeys</text>83 <path class="d-msg" d="M225,73 C190,58 175,52 143,45"/>84 <path class="d-msg" d="M225,137 C190,152 175,158 143,165"/>85 <path class="d-msg blue" d="M357,105 L417,105"/>86 <text class="d-label" x="170" y="80" text-anchor="middle">"e" / "a"</text>87 <text class="d-label" x="170" y="140" text-anchor="middle">"r"</text>88 <text class="d-label" x="387" y="98" text-anchor="middle">"p"</text>89 <circle r="4" fill="#f26a00">90 <animateMotion dur="2.6s" repeatCount="indefinite" path="M225,73 C190,58 175,52 143,45"/>91 </circle>92 </svg>93 </div>94 <figcaption>Fig. 84-1 — <b>Anatomy of a highlight.</b> One event references its source and its original authors.</figcaption>95 </figure>9697 <h2 class="bar" id="spec"><span class="num">2</span> The Highlight Event</h2>98 <p>A highlight is an event of <code>kind:9802</code>. The <code>content</code> field carries the highlighted portion of the text, verbatim.</p>99 <p>The <code>content</code> may be empty. Use an empty <code>content</code> for highlights of media that is not text, for example <a href="94.html">NIP-94</a> audio or video files.</p>100101 <div class="crt">102 <div class="titlebar">Wire format - kind 9802 highlight</div>103<pre>{104 <span class="k">"kind"</span>: 9802,105 <span class="k">"content"</span>: <span class="c"><the highlighted text, or "" for non-text media></span>,106 <span class="k">"tags"</span>: [107 [<span class="s">"a"</span>, <span class="c"><kind:pubkey:d-value></span>] <span class="c">or ["e", <event-id>] or ["r", <url>]</span>108 [<span class="s">"p"</span>, <span class="c"><pubkey-hex></span>, <span class="c"><relay-url></span>, <span class="s">"author"</span>],109 [<span class="s">"context"</span>, <span class="c"><surrounding text, optional></span>],110 [<span class="s">"comment"</span>, <span class="c"><user commentary, optional></span>]111 ],112 <span class="c">... standard NIP-01 fields ...</span>113}</pre>114 </div>115116 <div class="tscroll"><table class="ref">117 <caption>Tag reference - kind 9802</caption>118 <tr><th>Tag</th><th>Requirement</th><th>Purpose</th></tr>119 <tr><td class="btn">e</td><td>SHOULD (one source tag)</td><td>Points to the highlighted nostr event by id.</td></tr>120 <tr><td class="btn">a</td><td>SHOULD (one source tag)</td><td>Points to the highlighted addressable event, for example a <a href="23.html">NIP-23</a> article.</td></tr>121 <tr><td class="btn">r</td><td>SHOULD (one source tag)</td><td>Points to the highlighted URL when the source is not a nostr event. In a quote highlight the source URL must carry the <code>source</code> marker.</td></tr>122 <tr><td class="btn">p</td><td>MAY, repeatable</td><td>Credits an original author of the material. A role such as <code>author</code> or <code>editor</code> may follow as the last value.</td></tr>123 <tr><td class="btn">context</td><td>MAY</td><td>Carries the surrounding text when the highlight is a subset of a paragraph.</td></tr>124 <tr><td class="btn">comment</td><td>MAY</td><td>Carries the user's own commentary. Its presence turns the event into a quote highlight. See §5.</td></tr>125 </table></div>126127 <h2 class="bar" id="references"><span class="num">3</span> References: Tagging the Source</h2>128 <p>A highlight should tag the source of the highlighted material. This rule applies to nostr-native sources and to external sources.</p>129 <ul>130 <li>Use an <code>a</code> or <code>e</code> tag when the source is a nostr event.</li>131 <li>Use an <code>r</code> tag when the source is a URL.</li>132 </ul>133 <p>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 <code>utm_source</code> and similar parameters.</p>134 <div class="box warn">135 <span class="tag">Warning!</span>136 <p>Dirty URLs split highlights. Two users who highlight the same article through different tracking links produce two different <code>r</code> values. Clients then cannot group the highlights. Strip the junk first.</p>137 </div>138139 <h2 class="bar" id="attribution"><span class="num">4</span> Attribution and Context</h2>140 <p>A client may add one or more <code>p</code> tags to a highlight. Each <code>p</code> tag credits an original author of the highlighted material. A role may be included as the last value of the tag, for example <code>author</code> or <code>editor</code>.</p>141 <p>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 <code><link rel="me" href="nostr:nprofile1..." /></code>. The <code>nostr:</code> URI scheme is defined in <a href="21.html">NIP-21</a>.</p>142 <div class="crt">143 <div class="titlebar">Attribution tags with roles</div>144<pre>{145 <span class="k">"tags"</span>: [146 [<span class="s">"p"</span>, <span class="c"><pubkey-hex></span>, <span class="c"><relay-url></span>, <span class="s">"author"</span>],147 [<span class="s">"p"</span>, <span class="c"><pubkey-hex></span>, <span class="c"><relay-url></span>, <span class="s">"author"</span>],148 [<span class="s">"p"</span>, <span class="c"><pubkey-hex></span>, <span class="c"><relay-url></span>, <span class="s">"editor"</span>]149 ]150 <span class="c">// other fields...</span>151}</pre>152 </div>153 <p>A client may also add a <code>context</code> 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.</p>154155 <h2 class="bar" id="quote"><span class="num">5</span> Quote Highlights</h2>156 <p>A user often wants to highlight a passage and comment on it in one step. Add a <code>comment</code> tag to the highlight to do this. The result is a <strong>quote highlight</strong>.</p>157 <p>Clients must render a quote highlight like a quote repost (see <a href="18.html">NIP-18</a>). 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 <code>kind:1</code> note. Two back-to-back notes look bad in micro-blogging clients.</p>158 <p>Quote highlights add two marker rules:</p>159 <ul>160 <li>A <code>p</code> tag that mentions a user in the comment must carry a <code>mention</code> marker. This separates mentions from <code>author</code> and <code>editor</code> attributions.</li>161 <li>An <code>r</code> tag for a URL that appears in the comment must carry a <code>mention</code> marker. The source URL of the highlight must carry the <code>source</code> marker instead.</li>162 </ul>163164 <figure class="diagram">165 <div class="frame">166 <svg viewBox="0 0 560 200" role="img" aria-label="A quote highlight renders as one note: the comment on top, the highlighted passage quoted below it">167 <rect class="d-actor" x="10" y="60" width="170" height="80" rx="8"/>168 <text class="d-actor-label" x="95" y="90" text-anchor="middle">kind 9802</text>169 <text class="d-note" x="95" y="108" text-anchor="middle">content + comment</text>170 <text class="d-note" x="95" y="124" text-anchor="middle">source + mention markers</text>171 <rect class="d-actor" x="330" y="20" width="220" height="160" rx="8"/>172 <text class="d-actor-label" x="440" y="45" text-anchor="middle">Rendered note</text>173 <rect x="350" y="58" width="180" height="40" rx="4" fill="#f26a00"/>174 <text class="d-label" x="440" y="82" text-anchor="middle" fill="#fff">comment text</text>175 <rect x="362" y="108" width="168" height="52" rx="4" fill="#2e5f9e"/>176 <text class="d-label" x="446" y="130" text-anchor="middle" fill="#fff">"highlighted passage"</text>177 <text class="d-label" x="446" y="148" text-anchor="middle" fill="#fff">— source</text>178 <path class="d-msg d-flow" d="M182,100 L327,100"/>179 <text class="d-label" x="255" y="92" text-anchor="middle">render</text>180 <circle r="4" fill="#f26a00">181 <animateMotion dur="2.6s" repeatCount="indefinite" path="M182,100 L327,100"/>182 </circle>183 </svg>184 </div>185 <figcaption>Fig. 84-2 — <b>Quote highlight rendering.</b> One event, one note: the comment quotes the highlight.</figcaption>186 </figure>187188 <div class="box tech">189 <span class="tag">Tech Note</span>190 <p>The source spec does not state the exact position of the <code>mention</code> and <code>source</code> markers inside the tag. It only says the tags "must have" the attribute. By analogy with the attribution roles, implementations place the marker as the last value of the tag. Also, the spec's attribution example is JSON with comments inside a fence labeled <code>yaml</code>.</p>191 </div>192193 <h2 class="bar" id="examples"><span class="num">6</span> Worked Example</h2>194 <p>A user reads a <a href="23.html">NIP-23</a> 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.</p>195 <div class="crt">196 <div class="titlebar">Highlight of a nostr article</div>197<pre><span class="send">→ ["EVENT", {198 "id": "7d10c5e1…",199 "pubkey": "9f3a22b1…",200 "created_at": 1749800000,201 "kind": 9802,202 "tags": [203 ["a", "30023:41fa9b76…:protocol-design", "wss://relay.example.com"],204 ["p", "41fa9b76…", "wss://relay.example.com", "author"],205 ["context", "Simple protocols survive. Complex protocols need committees, and committees need budgets."]206 ],207 "content": "Simple protocols survive.",208 "sig": "c04d11a2…"209}]</span>210<span class="recv">← ["OK", "7d10c5e1…", true, ""]</span></pre>211 </div>212 <div class="crt">213 <div class="titlebar">Quote highlight of a web page</div>214<pre><span class="send">→ ["EVENT", {215 "id": "e2b91c07…",216 "pubkey": "9f3a22b1…",217 "created_at": 1749803600,218 "kind": 9802,219 "tags": [220 ["r", "https://example.com/essays/keys", "source"],221 ["p", "b7e2ff40…", "wss://relay.example.com", "author"],222 ["p", "c91d0e55…", "wss://relay.example.com", "mention"],223 ["r", "https://example.com/glossary", "mention"],224 ["comment", "This is what nostr:npub1eyt… keeps saying. See also https://example.com/glossary"]225 ],226 "content": "Your keys are your identity.",227 "sig": "8fa3d971…"228}]</span>229<span class="recv">← ["OK", "e2b91c07…", true, ""]</span>230<span class="c">-- the client renders the comment as a note that quotes the highlight --</span></pre>231 </div>232 <p>Note the markers in the second event. The highlighted page carries <code>source</code>. The URL and pubkey mentioned inside the comment carry <code>mention</code>. The article author carries <code>author</code>.</p>233234 <h2 class="bar" id="history"><span class="num">7</span> Version History</h2>235 <p>NIP-84 arrived in late 2023 after the highlighter feature shipped in the Highlighter client. Notable changes, newest first:</p>236 <ul class="patchnotes">237 <li><span class="ver">2025</span><span class="when">2025-05</span>Documented the <code><link rel="me"></code> technique for finding a nostr pubkey on an HTML document (#1897).</li>238 <li><span class="ver">2025</span><span class="when">2025-04</span>Added quote highlights: the <code>comment</code> tag plus the <code>mention</code> and <code>source</code> markers (#1438).</li>239 <li class="minor"><span class="ver">2023-24</span><span class="when">2023-2024</span>Formatting passes, typo fixes, and removal of the in-file author list.</li>240 <li><span class="ver">2023</span><span class="when">2023-11</span>Removed the positional "range" mechanism days after merge; it can return later if needed.</li>241 <li><span class="ver">Origin</span><span class="when">2023-11</span>Pablo Fernandez proposed NIP-84 with kind 9802, references, attribution, and context (#501).</li>242 </ul>243244 <div class="credits">245 <h3 class="cardhead">Original Proposal - Credits</h3>246 <table>247 <tr><td>Author</td><td>Pablo Fernandez</td></tr>248 <tr><td>First commit</td><td>2023-11-07 — “NIP-84: Highlights” (<a href="https://github.com/nostr-protocol/nips/pull/501">PR #501</a>)</td></tr>249 <tr><td>Status</td><td>draft - optional — clients choose whether to support highlights</td></tr>250 <tr><td>Source</td><td><a href="https://github.com/nostr-protocol/nips/blob/master/84.md">84.md on GitHub</a> - <a href="https://github.com/nostr-protocol/nips/commits/master/84.md">full change history</a></td></tr>251 </table>252 </div>253254 <h2 class="bar"><span class="num">8</span> See Also</h2>255 <ul>256 <li><a href="01.html">NIP-01</a> — the base event format and the <code>e</code>, <code>p</code>, and <code>a</code> tags used here.</li>257 <li><a href="18.html">NIP-18</a> — quote reposts; quote highlights must render the same way.</li>258 <li><a href="23.html">NIP-23</a> — long-form articles, the most common nostr-native highlight source.</li>259 <li><a href="94.html">NIP-94</a> — file metadata; highlight audio or video with an empty <code>content</code>.</li>260 <li><a href="21.html">NIP-21</a> — the <code>nostr:</code> URI scheme used in <code>link rel="me"</code> attribution.</li>261 </ul>262 </div>263264 <aside>265 <div class="cartridge">266 <div class="inner">267 <h3 class="cardhead">Spec Card</h3>268 <div class="lights"><span class="led on"></span><span class="led on"></span><span class="led on"></span></div>269 <dl>270 <dt>Status</dt><dd><span class="chip draft">draft</span><span class="chip optional">optional</span></dd>271 <dt>Defines</dt><dd>kind 9802 - context/comment tags - source/mention markers</dd>272 <dt>Kind(s)</dt><dd>9802 (regular)</dd>273 <dt>Requires</dt><dd><a href="01.html">NIP-01</a>; renders per <a href="18.html">NIP-18</a></dd>274 <dt>Transport</dt><dd>standard relay flow - no new messages</dd>275 <dt>First commit</dt><dd>2023-11-07</dd>276 <dt>Last updated</dt><dd>2026-06-13</dd>277 </dl>278 </div>279 </div>280 </aside>281 </main>282283 <nav class="navbtns">284 <a href="7d.html">◀ NIP-7D: Forum Threads</a>285 <a href="85.html">NIP-85: Trusted Assertions ▶</a>286 </nav>287288 <footer class="pagefoot">289 <a href="../index.html">Nostr Protocol Manual</a>290 <span class="pageno">NIP 84 / F4</span>291 </footer>292</div>293294<script src="../assets/webmcp.js" defer></script>295</body>296</html>