guide-render: render or refuse the Markdown it used to get silently wrong

- Ordered lists keep their start number, and blank lines between items keep
  one list, so "1. a / blank / 2. b" no longer restarts at 1.
- ---, *** and ___ render as <hr />; ~~~ fences render as code.
- A setext underline (=== or --- under text) and a code fence indented
  under a list item now fail with MarkdownError instead of mis-rendering.
- A heading whose slug is a template id (## Content vs <main id="content">)
  takes the next suffix.

Every current guide page builds byte-identical. Tests cover each case.

Closes #168

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LpkeXRUqm7oDedPDk3QWtK

Author: TMHSDigital

site/lib/guide-render.mjs

@@ -3,10 +3,12 @@
  * entry bodies (tables, fenced code, blockquotes, numbered lists, ### headings),
  * so they get their own renderer; renderBlocks stays strict for entries.
  * Inline markup and links go through renderInline and the caller's resolver.
- * Images and raw HTML still fail the build, as on entry pages. Pure.
+ * Images and raw HTML still fail the build, as on entry pages, and so do the
+ * constructs it would otherwise get wrong: setext headings and code fences
+ * indented under a list item. Pure.
  */
 import { esc } from "./shared.mjs";
-import { MarkdownError, renderInline } from "./markdown.mjs";
+import { MarkdownError, renderInline, RESERVED_IDS } from "./markdown.mjs";
 
 /** GitHub's heading anchor, so links written for GitHub (licenses.md#cc-by) land here too. */
 export function headingSlug(text) {
@@ -41,6 +43,12 @@ function cells(line) {
   return out;
 }
 
+/** A thematic break: three or more of the same -, * or _ (spaces allowed between). */
+const isBreak = (line) => /^\s{0,3}([-*_])(\s*\1){2,}\s*$/.test(line);
+/** A setext underline (=== or ---) under a paragraph line. */
+const isSetext = (line) => /^\s{0,3}(=+|-+)\s*$/.test(line);
+const FENCE_RE = /^\s*(`{3,}|~{3,})/;
+
 const isSeparator = (line) => /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/.test(line);
 
 /**
@@ -59,7 +67,7 @@ export function renderGuide(md, { file, resolveLink }) {
   const fail = (n, what) => {
     throw new MarkdownError(`${file}:${n + 1}: ${what} is not supported on guide pages`);
   };
-  const isBlockStart = (l) => /^\s*(```|>|\||#{1,6}\s|[-*]\s|\d+[.)]\s)/.test(l);
+  const isBlockStart = (l) => /^\s*(```|~~~|>|\||#{1,6}\s|[-*]\s|\d+[.)]\s)/.test(l) || isBreak(l);
 
   while (i < ls.length) {
     const line = ls[i];
@@ -70,18 +78,29 @@ export function renderGuide(md, { file, resolveLink }) {
     if (/^\s*!\[/.test(line)) fail(i, "an image");
     if (/^\s*<(?!https?:\/\/)[A-Za-z!/]/.test(line)) fail(i, "raw HTML");
 
-    // Fenced code: literal, escaped.
-    if (/^\s*```/.test(line)) {
-      const lang = line.trim().slice(3).trim();
+    // Fenced code (``` or ~~~): literal, escaped. It closes on a fence of
+    // the same character at least as long as the opening one.
+    const fence = line.match(FENCE_RE);
+    if (fence) {
+      if (/^\s+/.test(line)) fail(i, "an indented code fence (inside a list item)");
+      const mark = fence[1];
+      const lang = line.trim().slice(mark.length).trim();
+      const closes = new RegExp(`^\\s*\\${mark[0]}{${mark.length},}\\s*$`);
       const body = [];
       i += 1;
-      while (i < ls.length && !/^\s*```/.test(ls[i])) body.push(ls[i++]);
+      while (i < ls.length && !closes.test(ls[i])) body.push(ls[i++]);
       if (i >= ls.length) fail(i - 1, "an unclosed code fence");
       i += 1;
       html.push(`<pre class="guide-code"${lang ? ` data-lang="${esc(lang)}"` : ""}><code>${esc(body.join("\n"))}</code></pre>`);
       continue;
     }
 
+    if (isBreak(line)) {
+      html.push("<hr />");
+      i += 1;
+      continue;
+    }
+
     const h = line.match(/^(#{1,6})\s+(.*?)\s*#*\s*$/);
     if (h) {
       const level = h[1].length;
@@ -96,9 +115,14 @@ export function renderGuide(md, { file, resolveLink }) {
         continue;
       }
       const base = headingSlug(h[2]);
-      const n = seen.get(base) || 0;
+      let n = seen.get(base) || 0;
+      let id = n ? `${base}-${n}` : base;
+      // The page template owns some ids (<main id="content">): take the next suffix.
+      while (RESERVED_IDS.has(id)) {
+        n += 1;
+        id = `${base}-${n}`;
+      }
       seen.set(base, n + 1);
-      const id = n ? `${base}-${n}` : base;
       const tag = `h${Math.min(level, 4)}`;
       html.push(`<${tag} id="${esc(id)}">${inline(h[2])}</${tag}>`);
       i += 1;
@@ -131,6 +155,7 @@ export function renderGuide(md, { file, resolveLink }) {
     const li = line.match(listRe);
     if (li) {
       const ordered = /\d/.test(li[1]);
+      const start = ordered ? parseInt(li[1], 10) : 1;
       const items = [];
       while (i < ls.length) {
         const m = ls[i].match(listRe);
@@ -140,15 +165,34 @@ export function renderGuide(md, { file, resolveLink }) {
         } else if (items.length && ls[i].trim() && /^\s+/.test(ls[i]) && !isBlockStart(ls[i])) {
           items[items.length - 1] += ` ${ls[i].trim()}`;
           i += 1;
+        } else if (items.length && FENCE_RE.test(ls[i]) && /^\s+/.test(ls[i])) {
+          fail(i, "an indented code fence (inside a list item)");
+        } else if (items.length && !ls[i].trim()) {
+          // Blank lines between items of the same list keep one list
+          // (a "loose" list), so 1. a / blank / 2. b stays numbered 1, 2.
+          let j = i;
+          while (j < ls.length && !ls[j].trim()) j += 1;
+          const next = j < ls.length ? ls[j].match(listRe) : null;
+          if (next && /\d/.test(next[1]) === ordered && !/^\s+/.test(ls[j])) i = j;
+          else if (j < ls.length && FENCE_RE.test(ls[j]) && /^\s+/.test(ls[j])) fail(j, "an indented code fence (inside a list item)");
+          else break;
         } else break;
       }
       const tag = ordered ? "ol" : "ul";
-      html.push(`<${tag}>${items.map((t) => `<li>${inline(t)}</li>`).join("")}</${tag}>`);
+      const startAttr = ordered && start !== 1 ? ` start="${start}"` : "";
+      html.push(`<${tag}${startAttr}>${items.map((t) => `<li>${inline(t)}</li>`).join("")}</${tag}>`);
       continue;
     }
 
     const para = [];
-    while (i < ls.length && ls[i].trim() && !isBlockStart(ls[i])) para.push(ls[i++].trim());
+    while (i < ls.length && ls[i].trim() && !isBlockStart(ls[i])) {
+      // A === or --- under paragraph text is a setext heading on GitHub.
+      if (para.length && isSetext(ls[i])) fail(i, "a setext heading underline (use ## instead)");
+      para.push(ls[i++].trim());
+    }
+    if (para.length && i < ls.length && isBreak(ls[i]) && /^\s{0,3}-/.test(ls[i])) {
+      fail(i, "a setext heading underline (use ## instead)");
+    }
     if (!para.length) {
       // A line that looks like a block start but matched nothing above.
       para.push(ls[i++].trim());

site/lib/lib.test.mjs

@@ -1261,6 +1261,21 @@ eq("search: q from the URL is capped", readState(`?q=${"a".repeat(5000)}`, { q:
   let threw = "";
   try { renderGuide("# T\n\n![x](a.png)\n", { file: "g.md", resolveLink: pass }); } catch (e) { threw = e.message; }
   has("guide: images refused", threw, "g.md:3: an image is not supported");
+  const gr = (md) => renderGuide(`# T\n\n${md}`, { file: "g.md", resolveLink: pass }).html;
+  has("guide: an ordered list keeps its start number", gr("3. third\n4. fourth\n"), '<ol start="3"><li>third</li><li>fourth</li></ol>');
+  has("guide: a loose ordered list stays one list", gr("1. a\n\n2. b\n"), "<ol><li>a</li><li>b</li></ol>");
+  has("guide: a loose bullet list stays one list", gr("- a\n\n- b\n\nAfter.\n"), "<ul><li>a</li><li>b</li></ul>\n<p>After.</p>");
+  has("guide: a paragraph between lists splits them", gr("1. a\n\nText.\n\n2. b\n"), '<ol start="2"><li>b</li></ol>');
+  has("guide: --- is a thematic break", gr("Para.\n\n---\n\nNext.\n"), "<p>Para.</p>\n<hr />\n<p>Next.</p>");
+  has("guide: *** is a thematic break", gr("***\n"), "<hr />");
+  throws("guide: --- under text (a setext heading) fails", () => gr("Para\n---\n"), "a setext heading underline");
+  throws("guide: === under text (a setext heading) fails", () => gr("Para\n===\n"), "a setext heading underline");
+  has("guide: ~~~ fences render as code", gr("~~~js\nlet a = **1**;\n~~~\n"), '<pre class="guide-code" data-lang="js"><code>let a = **1**;</code></pre>');
+  has("guide: a ``` line inside a ~~~ fence is literal", gr("~~~\n```\n~~~\n"), "<code>```</code>");
+  throws("guide: a fence indented under a list item fails", () => gr("1. step\n   ```sh\n   x\n   ```\n"), "an indented code fence");
+  throws("guide: a fence after a blank line under a list item fails", () => gr("- step\n\n  ```\n  x\n  ```\n"), "an indented code fence");
+  has("guide: ## Content does not take the template's id", gr("## Content\n"), '<h2 id="content-1">Content</h2>');
+  has("guide: a second ## Content continues the count", gr("## Content\n\n## Content\n"), '<h2 id="content-2">Content</h2>');
 }
 
 /* new-entry --from-issue (scaffold.mjs) ------------------------------------ */

site/lib/markdown.mjs

@@ -33,7 +33,7 @@ function marks(escaped) {
 }
 
 /** Ids the page templates use themselves; a heading must not take one. */
-const RESERVED_IDS = new Set([
+export const RESERVED_IDS = new Set([
   "attribution-string",
   "content",
   "copy-attribution",