From 7a32ba6fd23847beaa32a15ace39d499eacdbbb8 Mon Sep 17 00:00:00 2001
From: Karl Bartel <karl@karl.berlin>
Date: Mon, 18 May 2026 09:49:18 +0200
Subject: [PATCH] Specify punctuation handling for auto-generated heading IDs

Replace each maximal run of non-alphanumeric ASCII characters with
`-` and trim leading/trailing `-`.  This settles remove-vs-replace
as replace and removes the previous exceptions for individual
punctuation characters (#391).
---
 changelog.md    | 6 ++++++
 doc/syntax.html | 7 ++++---
 doc/syntax.md   | 7 ++++---
 3 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/changelog.md b/changelog.md
index 8f2c2b3..9567782 100644
--- a/changelog.md
+++ b/changelog.md
@@ -107,3 +107,9 @@
   * Use the JavaScript reference implementation, not the Lua one
     to generate expected output in syntax.html.
 
+  * Specify punctuation handling for auto-generated heading IDs:
+    each maximal run of non-alphanumeric ASCII characters is
+    replaced with `-`, and leading/trailing `-` are trimmed.  This
+    settles remove-vs-replace as replace and removes the previous
+    exceptions for individual punctuation characters (#391).
+
diff --git a/doc/syntax.html b/doc/syntax.html
index 0fd8adf..2cca21d 100644
--- a/doc/syntax.html
+++ b/doc/syntax.html
@@ -1753,9 +1753,10 @@ <h3>Links to headings</h3>
 do not have explicit identifiers attached to them.
 The identifier is formed by taking the plain text content of
 the heading, excluding non-textual elements such as footnote
-references and symbols, removing punctuation (other than <code>_</code>
-and <code>-</code>), replacing spaces with <code>-</code>, and if necessary for
-uniqueness, adding a numerical suffix.</p>
+references and symbols, replacing each maximal run of
+non-alphanumeric ASCII characters with <code>-</code>, removing any
+leading or trailing <code>-</code>, and if necessary for uniqueness,
+adding a numerical suffix.</p>
 <p>For example, <code># Introduction[^1]</code> generates the identifier
 <code>Introduction</code>, not <code>Introduction1</code>.</p>
 <div class="example">
diff --git a/doc/syntax.md b/doc/syntax.md
index f7fff4a..0c0f2bd 100644
--- a/doc/syntax.md
+++ b/doc/syntax.md
@@ -765,9 +765,10 @@ Identifiers are added automatically to any headings that
 do not have explicit identifiers attached to them.
 The identifier is formed by taking the plain text content of
 the heading, excluding non-textual elements such as footnote
-references and symbols, removing punctuation (other than `_`
-and `-`), replacing spaces with `-`, and if necessary for
-uniqueness, adding a numerical suffix.
+references and symbols, replacing each maximal run of
+non-alphanumeric ASCII characters with `-`, removing any
+leading or trailing `-`, and if necessary for uniqueness,
+adding a numerical suffix.
 
 For example, `# Introduction[^1]` generates the identifier
 `Introduction`, not `Introduction1`.