Permalinks ---Org's own =<>=, made visible---

⭐ The code lives at github.com/alhassy/org-special-block-extras —star it, or discuss it there!

Sometimes we want to point explicitly at a particular location in an article, such as within a #+begin_details block. Org already has two kinds of target for this; we merely make the first one visible.

Org's <<X>> —a dedicated target— names a spot X. Within Emacs, [[X]] jumps there by C-c C-o. Upon export, the target is an invisible anchor: in HTML, <a id="orgNNNNNNN"></a>, whose id is random unless org-html-prefer-user-labels is set; in LaTeX, \label{orgNNNNNNN}. The text X itself never shows.
Org's <<<X>>> —a radio target— is a definition site: X shows as usual, and every mention of X elsewhere in the buffer becomes a link back to it, sans any [[⋯]].

With org-special-block-extras-mode on, in HTML:

<<X>> exports as a clickable 🔗, a permalink to itself —it looks and behaves like the links GitHub generates for a heading. Click it, and the URL ends in #X, ready for a reader to copy. The id is X itself, its whitespace as dashes: <<Euler's lemma>> ↦ #Euler's-lemma, which [[Euler's lemma]] links to as well.
<<<X>>> looks just as Org renders it; only its id becomes X too, so #monoid rather than #orgNNNNNNN.
Other backends are untouched; e.g., LaTeX keeps Org's \label.

Two targets whose names differ only in whitespace, such as <<a b>> and <<a-b>>, share an id; we name them apart.

Going forward, we could give every heading such a permalink too, producing clickable org-headings similar to Github's —the necessary ingredients are likely here.

﴾What You Write﴿

<<example-location>> (Click the icon and see the URL has changed!)

﴾What You Get﴿

(Click the icon and see the URL has changed!)

Tests

(deftest "It works as expected: We have an anchor with the given ID, and the default SVG chain icon."
  [target]
  (⇝ (⟰ "<<example-location>> (Click the icon and see the URL has changed!)")
     "<a class=\"anchor\" id=\"example-location\" href=\"#example-location\" aria-label=\"Permalink to example-location\"><svg"
     (* anything)
     "</svg></a> (Click the icon and see the URL has changed!)"
     (* anything)))

Generated by Emacs and Org-mode (•̀ᴗ•́)و

Life & Computing Science by Musa Al-hassy is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License