heading anchors

Author: mbostock

README.md

@@ -94,6 +94,7 @@ TODO
 - implicitly await ${…} expressions before calling display?
 - promote img, video, audio, and picture elements to file attachments
 - add rel="nofollow noindex" to external links by default
+- ✅ automatic anchor links for heading elements
 - themes
   - ✅ default light/dark theme
   - dashboard theme for wide layout

package.json

@@ -35,6 +35,7 @@
     "gray-matter": "^4.0.3",
     "highlight.js": "^11.8.0",
     "markdown-it": "^13.0.2",
+    "markdown-it-anchor": "^8.6.7",
     "mime": "^3.0.0",
     "send": "^0.18.0",
     "tsx": "^3.13.0",

public/style.css

@@ -358,6 +358,10 @@ figcaption {
   color: var(--syntax-unknown-variable);
 }
 
+a[href].observablehq-header-anchor {
+  color: inherit;
+}
+
 .observablehq--block {
   margin: 1rem 0;
 }

src/markdown.ts

@@ -1,6 +1,7 @@
 import matter from "gray-matter";
 import hljs from "highlight.js";
 import MarkdownIt from "markdown-it";
+import MarkdownItAnchor from "markdown-it-anchor";
 import type {RuleCore} from "markdown-it/lib/parser_core.js";
 import type {RuleInline} from "markdown-it/lib/parser_inline.js";
 import type {RenderRule} from "markdown-it/lib/renderer.js";
@@ -197,6 +198,7 @@ export function parseMarkdown(source: string, root: string): ParseResult {
       return ""; // defaults to escapeHtml(str)
     }
   });
+  md.use(MarkdownItAnchor, {permalink: MarkdownItAnchor.permalink.headerLink({class: "observablehq-header-anchor"})});
   md.inline.ruler.push("placeholder", transformPlaceholderInline);
   md.core.ruler.before("linkify", "placeholder", transformPlaceholderCore);
   md.renderer.rules.placeholder = makePlaceholderRenderer(root);
@@ -225,8 +227,14 @@ function findTitle(tokens: ReturnType<MarkdownIt["parse"]>): string | undefined
   for (const [i, token] of tokens.entries()) {
     if (token.type === "heading_open" && token.tag === "h1") {
       const next = tokens[i + 1];
-      if (next?.type === "inline" && next.children?.[0]?.type === "text") {
-        return next.content;
+      if (next?.type === "inline") {
+        const text = next.children
+          ?.filter((t) => t.type === "text")
+          .map((t) => t.content)
+          .join("");
+        if (text) {
+          return text;
+        }
       }
     }
   }

test/output/embedded-expression.html

@@ -1,2 +1,2 @@
-<h1>Embedded expression</h1>
+<h1 id="embedded-expression" tabindex="-1"><a class="observablehq-header-anchor" href="#embedded-expression">Embedded expression</a></h1>
 <p>One plus two is <span id="cell-1"></span>.</p>

test/output/fenced-code.html

@@ -1,4 +1,4 @@
-<h1>Fenced code</h1>
+<h1 id="fenced-code" tabindex="-1"><a class="observablehq-header-anchor" href="#fenced-code">Fenced code</a></h1>
 <div id="cell-1" class="observablehq observablehq--block"></div>
 <pre><code class="language-js"><span class="hljs-keyword">function</span> <span class="hljs-title function_">add</span>(<span class="hljs-params">a, b</span>) {
   <span class="hljs-keyword">return</span> a + b;

test/output/heading-expression.html

@@ -1 +1 @@
-<h1><span id="cell-1"></span></h1>
+<h1 id="" tabindex="-1"><a class="observablehq-header-anchor" href="#"><span id="cell-1"></span></a></h1>

test/output/hello-world.html

@@ -1,2 +1,2 @@
-<h1>Hello, world!</h1>
+<h1 id="hello%2C-world!" tabindex="-1"><a class="observablehq-header-anchor" href="#hello%2C-world!">Hello, world!</a></h1>
 <p>This is a test.</p>

test/output/script-expression.html

@@ -1,4 +1,4 @@
-<h1>Script expression</h1>
+<h1 id="script-expression" tabindex="-1"><a class="observablehq-header-anchor" href="#script-expression">Script expression</a></h1>
 <script type="module">
 
 const subject = "world";

test/output/tex-expression.html

@@ -1,2 +1,2 @@
-<h1>Hello, <span id="cell-1"></span></h1>
+<h1 id="hello%2C" tabindex="-1"><a class="observablehq-header-anchor" href="#hello%2C">Hello, <span id="cell-1"></span></a></h1>
 <p>My favorite equation is <span id="cell-2"></span>.</p>