Commit 50fcdc7 h

Pat Ambrosio · 26-09-01 09:06

Make every passage addressable, not just every heading

Changes: 4 files +326 -3

Changes (Side-by-Side)

Raw

commit 50fcdc73f88be439fd2f277fd7325c0502d61f13
Author: Pat Ambrosio <cp.ambrosio@gmail.com>
Date:   Tue Sep 1 09:06:32 2026 +0800

    Make every passage addressable, not just every heading
    
    Headings have carried ids for a while, which is what makes a link like
    /actions#validate resolve. Paragraphs did not, so a reader could point at
    a section but never at the sentence they actually meant.
    
    Each paragraph now carries p-<hash of its own text>. Derived from the
    content rather than the position, so a permalink survives edits elsewhere
    on the page: insert three paragraphs above one, or reorder the sections
    around it, and the link still lands. It breaks only when that paragraph's
    own wording changes, which is the honest failure -- the text someone
    linked to is not there any more. A positional p-7 would keep resolving
    after an insertion and quietly point at the wrong paragraph, which is
    worse than breaking, because the link still looks like it works.
    
    The hash is FNV-1a written in awk rather than a call out to md5sum: a
    page has hundreds of paragraphs and a sub-process each measured ~1.9ms,
    around 0.6s of build time here for nothing. Checked against all 776
    paragraphs on the site -- no collisions between different texts. Two
    paragraphs with identical words do collide by construction; the second
    takes a -2 suffix so both stay reachable.
    
    The ids alone are undiscoverable -- a reader would have to open the
    source to find one -- so hovering a heading or paragraph reveals a mark
    that copies the full URL, and following a permalink marks what was
    linked. The mark is hidden until hover or focus, so prose is not littered
    and a keyboard user can still reach it, and hidden entirely where there
    is no hover at all. The address bar is updated whether or not the
    clipboard write succeeds, so the link is always obtainable.
    
    The affordance script waits for DOMContentLoaded. Its tag sits in the
    body and the first version ran before the content existed, adding no
    marks at all.
    
    One existing test counted '<p><a href="/docs/' to check a generated
    listing puts each entry on its own row. Paragraphs now open with an id,
    so the literal stopped matching while the behaviour was unchanged; it
    matches the tag rather than the exact bytes now. The test asserting that
    only headings carry ids was the invariant this replaces, and is now four
    tests over the new contract.

diff --git a/share/jenny/layout/page.sh b/share/jenny/layout/page.sh
index 672f7ba..3c48745 100755
--- a/share/jenny/layout/page.sh
+++ b/share/jenny/layout/page.sh
@@ -890,6 +890,34 @@ cat << _EOF_
            while their siblings were bold. Deeper headings stay regular -- they
            sit inside a section rather than opening one. */
         .contents :is(h1, h2) { font-weight: bold; }
+        /* Deep-link mark. Hidden until the passage is hovered or the mark
+           itself is focused, so a page of prose is not littered with symbols;
+           keyboard users reach it by tabbing, which is why focus counts. */
+        .anchor-link {
+          margin-left: .4em; text-decoration: none; opacity: 0;
+          color: var(--text-muted); font-weight: normal; cursor: pointer;
+        }
+        :is(h1, h2, h3, h4, p):hover > .anchor-link,
+        .anchor-link:focus { opacity: 1; }
+        /* Coarse pointers have no hover, so the mark would never appear and
+           would only take up room. */
+        @media (hover: none) { .anchor-link { display: none; } }
+        /* The passage a permalink pointed at, marked rather than animated: a
+           reader arriving mid-document needs to see which paragraph was meant,
+           and a flash they might miss does not tell them. */
+        .target-flash {
+          background-color: var(--bg-secondary);
+          box-shadow: 0 0 0 .4em var(--bg-secondary);
+          border-radius: 2px;
+        }
+        .copy-toast {
+          position: fixed; left: 50%; bottom: 2em; transform: translate(-50%, .5em);
+          background-color: var(--bg-secondary); color: var(--text-primary);
+          border: 1px solid var(--border-light); border-radius: 3px;
+          padding: .5em 1em; font-size: .875em; z-index: 3000;
+          opacity: 0; pointer-events: none;
+        }
+        .copy-toast.show { opacity: 1; transform: translate(-50%, 0); }
         /* Every heading is body size, which keeps the page even but leaves a
            section heading reading as a stray line of capitals: uppercase alone
            does not say "new section". A rule above says it structurally rather
@@ -1183,6 +1211,74 @@ cat << _EOF_
             localStorage.setItem('theme', newTheme);
           });
 
+          // Deep links: a heading or paragraph carries an id, and hovering it
+          // offers a mark that copies the link to that exact place. Without the
+          // affordance the ids are there but undiscoverable -- a reader would
+          // have to open the source to find one.
+          function initAnchors() {
+            var targets = document.querySelectorAll('.contents :is(h1,h2,h3,h4)[id], .contents p[id]');
+            if (!targets.length) return;
+
+            var toast = null;
+            function flash(msg) {
+              if (!toast) {
+                toast = document.createElement('div');
+                toast.className = 'copy-toast';
+                document.body.appendChild(toast);
+              }
+              toast.textContent = msg;
+              toast.classList.add('show');
+              clearTimeout(toast._t);
+              toast._t = setTimeout(function() { toast.classList.remove('show'); }, 1600);
+            }
+
+            targets.forEach(function(el) {
+              var a = document.createElement('a');
+              a.className = 'anchor-link';
+              a.href = '#' + el.id;
+              a.setAttribute('aria-label', 'Copy link to this passage');
+              a.textContent = '\u00B6';
+              a.addEventListener('click', function(e) {
+                e.preventDefault();
+                var url = location.origin + location.pathname + '#' + el.id;
+                // The address bar is updated either way, so the link is
+                // obtainable even where the clipboard is unavailable.
+                history.replaceState(null, '', '#' + el.id);
+                if (navigator.clipboard && navigator.clipboard.writeText) {
+                  navigator.clipboard.writeText(url).then(
+                    function() { flash('Link copied'); },
+                    function() { flash('Press \u2318/Ctrl+C to copy'); }
+                  );
+                } else {
+                  flash('Press \u2318/Ctrl+C to copy');
+                }
+              });
+              el.appendChild(a);
+            });
+
+            // Mark whatever the reader arrived at, so a permalink lands on
+            // something visibly identified rather than just scrolled to.
+            function markTarget() {
+              document.querySelectorAll('.target-flash').forEach(function(e) {
+                e.classList.remove('target-flash');
+              });
+              if (!location.hash) return;
+              var t = null;
+              try { t = document.querySelector(location.hash); } catch (err) { return; }
+              if (t) t.classList.add('target-flash');
+            }
+            window.addEventListener('hashchange', markTarget);
+            markTarget();
+          }
+          // The script tag sits in the body, so at parse time the content it
+          // needs may not exist yet -- the first version ran before any of it
+          // was there and silently added nothing.
+          if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', initAnchors);
+          } else {
+            initAnchors();
+          }
+
           // Initialize footnote and citation tooltips
           function initTooltips() {
             // Footnotes: create tooltip elements with cloned content
diff --git a/share/jenny/layout/post.sh b/share/jenny/layout/post.sh
index 926a1c8..1f05596 100755
--- a/share/jenny/layout/post.sh
+++ b/share/jenny/layout/post.sh
@@ -711,6 +711,34 @@ cat << _EOF_
            while their siblings were bold. Deeper headings stay regular -- they
            sit inside a section rather than opening one. */
         .contents :is(h1, h2) { font-weight: bold; }
+        /* Deep-link mark. Hidden until the passage is hovered or the mark
+           itself is focused, so a page of prose is not littered with symbols;
+           keyboard users reach it by tabbing, which is why focus counts. */
+        .anchor-link {
+          margin-left: .4em; text-decoration: none; opacity: 0;
+          color: var(--text-muted); font-weight: normal; cursor: pointer;
+        }
+        :is(h1, h2, h3, h4, p):hover > .anchor-link,
+        .anchor-link:focus { opacity: 1; }
+        /* Coarse pointers have no hover, so the mark would never appear and
+           would only take up room. */
+        @media (hover: none) { .anchor-link { display: none; } }
+        /* The passage a permalink pointed at, marked rather than animated: a
+           reader arriving mid-document needs to see which paragraph was meant,
+           and a flash they might miss does not tell them. */
+        .target-flash {
+          background-color: var(--bg-secondary);
+          box-shadow: 0 0 0 .4em var(--bg-secondary);
+          border-radius: 2px;
+        }
+        .copy-toast {
+          position: fixed; left: 50%; bottom: 2em; transform: translate(-50%, .5em);
+          background-color: var(--bg-secondary); color: var(--text-primary);
+          border: 1px solid var(--border-light); border-radius: 3px;
+          padding: .5em 1em; font-size: .875em; z-index: 3000;
+          opacity: 0; pointer-events: none;
+        }
+        .copy-toast.show { opacity: 1; transform: translate(-50%, 0); }
         /* Every heading is body size, which keeps the page even but leaves a
            section heading reading as a stray line of capitals: uppercase alone
            does not say "new section". A rule above says it structurally rather
@@ -955,6 +983,74 @@ cat << _EOF_
             localStorage.setItem('theme', newTheme);
           });
 
+          // Deep links: a heading or paragraph carries an id, and hovering it
+          // offers a mark that copies the link to that exact place. Without the
+          // affordance the ids are there but undiscoverable -- a reader would
+          // have to open the source to find one.
+          function initAnchors() {
+            var targets = document.querySelectorAll('.contents :is(h1,h2,h3,h4)[id], .contents p[id]');
+            if (!targets.length) return;
+
+            var toast = null;
+            function flash(msg) {
+              if (!toast) {
+                toast = document.createElement('div');
+                toast.className = 'copy-toast';
+                document.body.appendChild(toast);
+              }
+              toast.textContent = msg;
+              toast.classList.add('show');
+              clearTimeout(toast._t);
+              toast._t = setTimeout(function() { toast.classList.remove('show'); }, 1600);
+            }
+
+            targets.forEach(function(el) {
+              var a = document.createElement('a');
+              a.className = 'anchor-link';
+              a.href = '#' + el.id;
+              a.setAttribute('aria-label', 'Copy link to this passage');
+              a.textContent = '\u00B6';
+              a.addEventListener('click', function(e) {
+                e.preventDefault();
+                var url = location.origin + location.pathname + '#' + el.id;
+                // The address bar is updated either way, so the link is
+                // obtainable even where the clipboard is unavailable.
+                history.replaceState(null, '', '#' + el.id);
+                if (navigator.clipboard && navigator.clipboard.writeText) {
+                  navigator.clipboard.writeText(url).then(
+                    function() { flash('Link copied'); },
+                    function() { flash('Press \u2318/Ctrl+C to copy'); }
+                  );
+                } else {
+                  flash('Press \u2318/Ctrl+C to copy');
+                }
+              });
+              el.appendChild(a);
+            });
+
+            // Mark whatever the reader arrived at, so a permalink lands on
+            // something visibly identified rather than just scrolled to.
+            function markTarget() {
+              document.querySelectorAll('.target-flash').forEach(function(e) {
+                e.classList.remove('target-flash');
+              });
+              if (!location.hash) return;
+              var t = null;
+              try { t = document.querySelector(location.hash); } catch (err) { return; }
+              if (t) t.classList.add('target-flash');
+            }
+            window.addEventListener('hashchange', markTarget);
+            markTarget();
+          }
+          // The script tag sits in the body, so at parse time the content it
+          // needs may not exist yet -- the first version ran before any of it
+          // was there and silently added nothing.
+          if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', initAnchors);
+          } else {
+            initAnchors();
+          }
+
           // Initialize footnote and citation tooltips
           function initTooltips() {
             // Footnotes: create tooltip elements with cloned content
diff --git a/share/jenny/lib/md2html.awk b/share/jenny/lib/md2html.awk
index b5f2dce..f2ef676 100755
--- a/share/jenny/lib/md2html.awk
+++ b/share/jenny/lib/md2html.awk
@@ -365,6 +365,57 @@ function heading_id(t,   s) {
 	return s
 }
 
+# para_id <html>
+# The anchor a paragraph is addressable by: "p-" and a hash of the paragraph's
+# own text.
+#
+# Derived from the content rather than the position, so a permalink survives
+# edits elsewhere on the page -- insert three paragraphs above this one, or
+# reorder the sections around it, and the link still resolves. It breaks only
+# when this paragraph's own wording changes, which is the honest failure: the
+# text someone linked to is not there any more. A positional p-7 would keep
+# resolving after an insertion and quietly point at the wrong paragraph, which
+# is worse than breaking.
+#
+# Inline markup is stripped first so that editing a link's target, or wrapping
+# a word in emphasis, does not move the anchor.
+function para_id(t,   s) {
+	s = t
+	gsub(/<[^>]*>/, "", s)
+	gsub(/&[a-z]+;|&#[0-9]+;|&#x[0-9a-fA-F]+;/, "", s)
+	gsub(/[ \t]+/, " ", s)
+	sub(/^ /, "", s); sub(/ $/, "", s)
+	if (s == "") return ""
+	return "p-" fnv1a(s)
+}
+
+# fnv1a <string>
+# FNV-1a, 32 bits, in awk rather than by calling out to a hash program: a page
+# has hundreds of paragraphs and a sub-process each would be the slowest part
+# of the build. Checked against every paragraph in the site at the time it was
+# written -- no collisions between different texts.
+function fnv1a(s,   h, i, c, n) {
+	h = 2166136261
+	n = length(s)
+	for (i = 1; i <= n; i++) {
+		c = index(HASHCHARS, substr(s, i, 1))
+		if (c == 0) c = 32
+		h = xor32(h, c)
+		h = (h * 16777619) % 4294967296
+	}
+	return sprintf("%08x", h)
+}
+
+function xor32(a, b,   r, i, x, y) {
+	r = 0; i = 1
+	while (a > 0 || b > 0) {
+		x = a % 2; y = b % 2
+		if (x != y) r += i
+		a = int(a / 2); b = int(b / 2); i *= 2
+	}
+	return r
+}
+
 function printp(tag,   id) {
 	if(!match(text, /^[ 	]*$/)){
 		text = inline(text);
@@ -377,6 +428,19 @@ function printp(tag,   id) {
 				else
 					oprint("<" tag ">" text "</" tag ">");
 			}
+			else if(tag == "p"){
+				# Two paragraphs with the same words hash the same; the second
+				# and later take a suffix so every id on the page is unique.
+				id = para_id(text)
+				if(id != ""){
+					PARA_SEEN[id]++
+					if(PARA_SEEN[id] > 1)
+						id = id "-" PARA_SEEN[id]
+					oprint("<p id=\"" id "\">" text "</p>");
+				}
+				else
+					oprint("<p>" text "</p>");
+			}
 			else
 				oprint("<" tag ">" text "</" tag ">");
 		}
@@ -387,6 +451,9 @@ function printp(tag,   id) {
 }
 
 BEGIN {
+	# Character table for fnv1a: index() gives each byte a value, so the hash
+	# needs no ord() -- which one-true-awk does not have.
+	HASHCHARS = " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
 	blank = 0;
 	code = 0;
 	hr = 0;
diff --git a/test/regressions.sh b/test/regressions.sh
index f234b8e..6315aac 100755
--- a/test/regressions.sh
+++ b/test/regressions.sh
@@ -1134,7 +1134,8 @@ mkdir -p "$ix/pages/docs"
 printf '# Alpha One\n\nx\n' > "$ix/pages/docs/alpha.md"
 printf '# Beta Two\n\nx\n' > "$ix/pages/docs/beta.md"
 run_jenny_split "$ix"
-rows=$("$GREP" -c '<p><a href="/docs/' "$ix/.dist/docs/index.html")
+# A paragraph carries a deep-link id now, so the opening tag is no longer bare.
+rows=$("$GREP" -c '<p[^>]*><a href="/docs/' "$ix/.dist/docs/index.html")
 assert_eq "$rows" "2"
 assert_file_not_contains "$ix/.dist/docs/index.html" '<li><a href="/docs/'
 
@@ -1216,8 +1217,44 @@ it "a heading with no sluggable characters gets no id"
 out=$(md_render '## ---')
 assert_not_contains "$out" 'id=""'
 
-it "only headings carry ids"
-assert_not_contains "$(md_render 'Just a paragraph.')" 'id='
+it "a paragraph carries a deep-link id"
+# Headings were addressable and paragraphs were not, so a reader could link to
+# a section but not to the sentence they meant.
+assert_contains "$(md_render 'Just a paragraph.')" 'id="p-'
+
+it "a paragraph's id is derived from its own text, not its position"
+# The point of hashing the text: inserting a paragraph above must not move the
+# anchor of the one below it. A positional id would keep resolving after the
+# insertion and quietly point at the wrong paragraph, which is worse than
+# breaking, because the link still looks like it works.
+before=$(md_render 'Alpha text.
+
+Beta text.' | "$GREP" -o 'id="p-[a-f0-9]*"' | tail -1)
+after=$(md_render 'Inserted first.
+
+Alpha text.
+
+Beta text.' | "$GREP" -o 'id="p-[a-f0-9]*"' | tail -1)
+assert_eq "$before" "$after"
+
+it "an id changes when the paragraph's own words change"
+# The other half of the contract, and the honest failure: the text someone
+# linked to is not there any more, so the link should not silently land on
+# something else.
+one=$(md_render 'Alpha text.' | "$GREP" -o 'id="p-[a-f0-9]*"')
+two=$(md_render 'Alpha text edited.' | "$GREP" -o 'id="p-[a-f0-9]*"')
+if [ "$one" != "$two" ]; then pass; else fail "id did not change with the text: $one"; fi
+
+it "repeated text still gets unique ids"
+# Two paragraphs with the same words hash the same; ids on one page must not
+# collide or the second is unreachable.
+dup=$(md_render 'Same words.
+
+Same words.' | "$GREP" -c 'id="p-')
+assert_eq "$dup" "2"
+assert_contains "$(md_render 'Same words.
+
+Same words.')" '-2"'
 
 it "a change to the parser invalidates the lock"
 # The build signature covered the layouts but not the parser, so adding ids to
@@ -1386,6 +1423,33 @@ assert_file_contains "$dg/.dist/post/charted.html" '.contents :is(h1, h2) {'
 assert_file_contains "$dg/.dist/chart.html" 'width: 3ch;'
 assert_file_contains "$dg/.dist/chart.html" '.contents :is(h1, h2)::before {'
 
+it "a passage offers a mark that copies its link"
+# Ids alone are undiscoverable -- a reader would have to open the source to
+# find one. Hovering a heading or paragraph reveals a mark that copies the
+# full URL to that place.
+assert_file_contains "$dg/.dist/chart.html" "a.className = 'anchor-link';"
+assert_file_contains "$dg/.dist/post/charted.html" "a.className = 'anchor-link';"
+
+it "the mark is hidden until the passage is hovered or the mark focused"
+# Otherwise a page of prose is littered with symbols. Focus counts too, or a
+# keyboard user could never reach it.
+assert_file_contains "$dg/.dist/chart.html" '.anchor-link:focus { opacity: 1; }'
+assert_file_contains "$dg/.dist/chart.html" '@media (hover: none) { .anchor-link { display: none; } }'
+
+it "the link is obtainable even without the clipboard"
+# The address bar is updated whether or not the copy succeeds, so the reader
+# can always take the link from there.
+assert_file_contains "$dg/.dist/chart.html" "history.replaceState(null, '', '#' + el.id);"
+
+it "following a permalink marks what was linked"
+# A reader landing mid-document needs to see which passage was meant.
+assert_file_contains "$dg/.dist/chart.html" "t.classList.add('target-flash');"
+
+it "the anchors wait for the document"
+# The script tag sits in the body; the first version ran before the content
+# existed and silently added no marks at all.
+assert_file_contains "$dg/.dist/chart.html" "document.addEventListener('DOMContentLoaded', initAnchors);"
+
 it "a section heading is bold"
 # Every heading is body size, so weight is what separates a section heading
 # from the prose around it. h1 as well as h2: a page's title repeat is an h1,