@hraness/wordcell 0.22.2 → 0.22.4

package/src/publish-markdown.ts

@@ -41,9 +41,15 @@ function anchorId(text: string, used: Map<string, number>): string {
     .toLocaleLowerCase("en-US")
     .replace(VOID_SLUG, "-")
     .replace(/^[-._~]+|[-._~]+$/gu, "") || "section";
-  const seen = used.get(base) ?? 0;
+  let seen = used.get(base) ?? 0;
+  let id = seen === 0 ? base : `${base}-${seen + 1}`;
+  while (used.has(id)) {
+    seen += 1;
+    id = `${base}-${seen + 1}`;
+  }
   used.set(base, seen + 1);
-  return seen === 0 ? base : `${base}-${seen + 1}`;
+  used.set(id, 1);
+  return id;
 }
 
 function isExternalUrl(value: string): boolean {
@@ -80,7 +86,63 @@ function wikiDisplay(raw: string): { target: string; fragment: string; label: st
   };
 }
 
-function renderInline(text: string, ctx: PublishRenderContext): string {
+const FOOTNOTE_LIMITS = {
+  labelBytes: 128,
+  definitions: 256,
+  bodyBytes: 8_192,
+  bodyLines: 32,
+  references: 2_048,
+} as const;
+
+type Footnote = {
+  readonly body: string;
+  readonly authored: string;
+  invalid: boolean;
+  number?: number;
+  readonly references: string[];
+};
+
+type Footnotes = {
+  readonly byLabel: Map<string, Footnote | null>;
+  readonly numbered: Footnote[];
+  definitions: number;
+  references: number;
+  disabled: boolean;
+  /** Plain display projections omit admitted citation navigation only. */
+  readonly plain?: true;
+};
+
+function footnoteLabel(raw: string): string | undefined {
+  const label = raw.normalize("NFC");
+  if (label.length > FOOTNOTE_LIMITS.labelBytes || !/^[\p{L}\p{M}\p{N}._:-]+$/u.test(label)) return undefined;
+  return new TextEncoder().encode(label).byteLength <= FOOTNOTE_LIMITS.labelBytes ? label : undefined;
+}
+
+function footnoteNumber(note: Footnote, footnotes: Footnotes): number {
+  if (note.number === undefined) {
+    note.number = footnotes.numbered.length + 1;
+    footnotes.numbered.push(note);
+  }
+  return note.number;
+}
+
+function renderFootnoteReference(raw: string, label: string, footnotes: Footnotes): string {
+  const key = footnoteLabel(label);
+  const note = key === undefined ? undefined : footnotes.byLabel.get(key);
+  if (footnotes.disabled || note === undefined || note === null || note.invalid || footnotes.references >= FOOTNOTE_LIMITS.references) {
+    return `<span class="unresolved footnote-reference" aria-label="Unresolved footnote">${escapeHtml(raw)}</span>`;
+  }
+  const number = footnoteNumber(note, footnotes);
+  // Colons cannot occur in heading slugs, so authored headings cannot capture
+  // these targets. Raw labels never enter an HTML id or fragment.
+  const id = `wordcell:footnote-ref:${number}:${note.references.length + 1}`;
+  note.references.push(id);
+  footnotes.references += 1;
+  if (footnotes.plain) return "";
+  return `<sup><a id="${id}" href="#wordcell:footnote:${number}" role="doc-noteref" aria-label="Footnote ${number}">${number}</a></sup>`;
+}
+
+function renderInline(text: string, ctx: PublishRenderContext, footnotes?: Footnotes): string {
   let output = "";
   let cursor = 0;
   const length = text.length;
@@ -99,7 +161,7 @@ function renderInline(text: string, ctx: PublishRenderContext): string {
       if (closing !== -1) {
         const code = rest.slice(ticks.length, closing).replace(/\s+/gu, " ");
         output += `<code>${escapeHtml(code)}</code>`;
-        cursor += ticks.length + closing + ticks.length;
+        cursor += closing + ticks.length;
         continue;
       }
       pushText("`");
@@ -198,6 +260,7 @@ function renderInline(text: string, ctx: PublishRenderContext): string {
       if (closing !== -1 && rest[closing + 1] === "(") {
         const destination = readDestination(rest, closing + 2);
         if (destination !== null) {
+          // Supported explicit links take precedence over footnote markers.
           const label = renderInline(rest.slice(1, closing), ctx);
           const target = destination.target;
           const asset = ctx.resolveAsset(target, ctx.source);
@@ -219,6 +282,14 @@ function renderInline(text: string, ctx: PublishRenderContext): string {
           continue;
         }
       }
+      if (footnotes !== undefined && rest.startsWith("[^")) {
+        const end = rest.indexOf("]", 2);
+        if (end !== -1) {
+          output += renderFootnoteReference(rest.slice(0, end + 1), rest.slice(2, end), footnotes);
+          cursor += end + 1;
+          continue;
+        }
+      }
       pushText("[");
       cursor += 1;
       continue;
@@ -249,7 +320,7 @@ function renderInline(text: string, ctx: PublishRenderContext): string {
     if (emphasis !== undefined && emphasis !== "_") {
       const closing = rest.indexOf(emphasis, emphasis.length);
       if (closing > emphasis.length) {
-        const inner = renderInline(rest.slice(emphasis.length, closing), ctx);
+        const inner = renderInline(rest.slice(emphasis.length, closing), ctx, footnotes);
         const tag = emphasis === "**" || emphasis === "__"
           ? "strong"
           : emphasis === "~~"
@@ -265,7 +336,7 @@ function renderInline(text: string, ctx: PublishRenderContext): string {
     if (emphasis === "_") {
       const closing = rest.indexOf("_", 1);
       if (closing > 1) {
-        output += `<em>${renderInline(rest.slice(1, closing), ctx)}</em>`;
+        output += `<em>${renderInline(rest.slice(1, closing), ctx, footnotes)}</em>`;
         cursor += closing + 1;
         continue;
       }
@@ -398,49 +469,145 @@ function tableCells(line: string): string[] {
   return cells.map((cell) => cell.trim());
 }
 
-/** Render authored Markdown to a sanitized HTML fragment. */
-export function renderMarkdownToHtml(content: string, ctx: PublishRenderContext): string {
-  const lines = content.split("\n");
-  // Strip frontmatter.
-  let start = 0;
-  if (lines[0]?.trim() === "---") {
-    for (let index = 1; index < lines.length; index += 1) {
-      if (lines[index]?.trim() === "---" || lines[index]?.trim() === "...") {
-        start = index + 1;
-        break;
+type ListPart =
+  | { readonly type: "open" | "close"; readonly ordered: boolean }
+  | { readonly type: "item"; readonly text: string; readonly checked?: boolean }
+  | { readonly type: "continuation"; readonly text: string };
+
+type MarkdownBlock =
+  | { readonly type: "paragraph"; readonly text: string }
+  | { readonly type: "heading"; readonly level: number; readonly text: string }
+  | { readonly type: "code"; readonly language: string; readonly text: string }
+  | { readonly type: "break" }
+  | { readonly type: "quote"; readonly blocks: readonly MarkdownBlock[] }
+  | { readonly type: "table"; readonly header: readonly string[]; readonly rows: readonly string[][] }
+  | { readonly type: "list"; readonly ordered: boolean; readonly parts: readonly ListPart[] }
+  | { readonly type: "literal"; readonly text: string }
+  | { readonly type: "footnote"; readonly note: Footnote };
+
+type Comments = { closing?: "-->" | "%%"; code?: string };
+
+/** Strip comments only in prose; code blocks never pass through this scanner. */
+function withoutComments(line: string, comments: Comments, continuesCode?: (ticks: string) => boolean): string {
+  let text = "";
+  let cursor = 0;
+  while (cursor < line.length) {
+    if (comments.code !== undefined) {
+      const end = line.indexOf(comments.code, cursor);
+      if (end === -1) return text + line.slice(cursor);
+      const next = end + comments.code.length;
+      text += line.slice(cursor, next);
+      cursor = next;
+      delete comments.code;
+      continue;
+    }
+    if (comments.closing !== undefined) {
+      const end = line.indexOf(comments.closing, cursor);
+      if (end === -1) return text;
+      cursor = end + comments.closing.length;
+      delete comments.closing;
+      continue;
+    }
+    const rest = line.slice(cursor);
+    if (rest[0] === "\\" && rest.length > 1) {
+      text += rest.slice(0, 2);
+      cursor += 2;
+      continue;
+    }
+    if (rest[0] === "`") {
+      const ticks = /^`+/u.exec(rest)?.[0] ?? "`";
+      const closing = rest.indexOf(ticks, ticks.length);
+      if (closing !== -1) {
+        const end = closing + ticks.length;
+        text += rest.slice(0, end);
+        cursor += end;
+        continue;
+      }
+      if (continuesCode?.(ticks) === true) {
+        comments.code = ticks;
+        return text + rest;
       }
     }
+    if (rest.startsWith("<!--") || rest.startsWith("%%")) {
+      comments.closing = rest.startsWith("<!--") ? "-->" : "%%";
+      cursor += comments.closing === "-->" ? 4 : 2;
+      continue;
+    }
+    text += rest[0] ?? "";
+    cursor += 1;
   }
+  return text;
+}
 
-  const anchors = new Map<string, number>();
-  const html: string[] = [];
-  let index = start;
-  let inComment = false;
+function paragraphBoundary(line: string, next: string): boolean {
+  return line.trim() === "" || /^(?: {4}|\t|#{1,6}\s|\s{0,3}>|\s{0,3}(?:`{3,}|~{3,}))/u.test(line)
+    || listMarker(line) !== undefined || (line.includes("|") && isTableDivider(next))
+    || /^\s{0,3}(?:(?:\*\s*){3,}|(?:-\s*){3,}|(?:_\s*){3,})$/u.test(line);
+}
 
+function hasContinuedInlineCode(lines: readonly string[], start: number, ticks: string): boolean {
+  for (let index = start; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    if (paragraphBoundary(line, lines[index + 1] ?? "")) return false;
+    if (line.includes(ticks)) return true;
+  }
+  return false;
+}
+
+function admitFootnote(rawLabel: string, body: readonly string[], authored: readonly string[], footnotes: Footnotes): Footnote {
+  const text = body.join("\n");
+  const label = footnoteLabel(rawLabel);
+  const note: Footnote = {
+    body: text,
+    authored: authored.join("\n"),
+    invalid: label === undefined || body.length > FOOTNOTE_LIMITS.bodyLines || text.length > FOOTNOTE_LIMITS.bodyBytes
+      || new TextEncoder().encode(text).byteLength > FOOTNOTE_LIMITS.bodyBytes || text.trim() === "",
+    references: [],
+  };
+  footnotes.definitions += 1;
+  if (footnotes.definitions > FOOTNOTE_LIMITS.definitions) {
+    footnotes.disabled = true;
+    footnotes.byLabel.clear();
+  }
+  if (!footnotes.disabled && label !== undefined) {
+    if (footnotes.byLabel.has(label)) {
+      const prior = footnotes.byLabel.get(label);
+      if (prior !== undefined && prior !== null) prior.invalid = true;
+      note.invalid = true;
+      footnotes.byLabel.set(label, null);
+    } else {
+      footnotes.byLabel.set(label, note.invalid ? null : note);
+    }
+  }
+  return note;
+}
+
+/** One block scan owns both rendering precedence and definition admission. */
+function parseMarkdownBlocks(content: string, footnotes: Footnotes, topLevel: boolean): MarkdownBlock[] {
+  const lines = content.split("\n");
+  let index = 0;
+  if (topLevel && lines[0]?.trim() === "---") {
+    for (let cursor = 1; cursor < lines.length; cursor += 1) {
+      if (lines[cursor]?.trim() === "---" || lines[cursor]?.trim() === "...") {
+        index = cursor + 1;
+        break;
+      }
+    }
+  }
+  const blocks: MarkdownBlock[] = [];
+  const comments: Comments = {};
   const paragraph: string[] = [];
   const flushParagraph = (): void => {
     if (paragraph.length === 0) return;
-    html.push(`<p>${renderInline(paragraph.join("\n").replace(/\n/gu, " "), ctx)}</p>`);
+    blocks.push({ type: "paragraph", text: paragraph.join(" ") });
     paragraph.length = 0;
   };
 
   while (index < lines.length) {
-    const line = lines[index] ?? "";
-
-    // HTML comments and Obsidian %% comments are stripped entirely.
-    if (inComment) {
-      const close = line.indexOf("-->");
-      index += 1;
-      if (close !== -1) inComment = false;
-      continue;
-    }
-    if (line.trim().startsWith("%%") && line.trim().endsWith("%%") && line.trim().length > 3) {
-      index += 1;
-      continue;
-    }
-
-    // Fenced code.
-    const fence = /^\s{0,3}(`{3,}|~{3,})([^`]*)$/u.exec(line);
+    const raw = lines[index] ?? "";
+    // Code has precedence over prose comments and footnote definitions.
+    const inCode = comments.code !== undefined;
+    const fence = comments.closing === undefined && !inCode ? /^\s{0,3}(`{3,}|~{3,})([^`]*)$/u.exec(raw) : null;
     if (fence !== null) {
       flushParagraph();
       const marker = fence[1] ?? "```";
@@ -450,151 +617,262 @@ export function renderMarkdownToHtml(content: string, ctx: PublishRenderContext)
       while (index < lines.length) {
         const candidate = lines[index] ?? "";
         const close = /^\s{0,3}(`{3,}|~{3,})\s*$/u.exec(candidate);
-        if (close !== null && (close[1] ?? "")[0] === marker[0] && (close[1] ?? "").length >= marker.length) {
-          break;
-        }
+        if (close !== null && (close[1] ?? "")[0] === marker[0] && (close[1] ?? "").length >= marker.length) break;
         body.push(candidate);
         index += 1;
       }
       index += 1;
-      const className = language === "" ? "" : ` class="language-${escapeAttribute(language)}"`;
-      html.push(`<pre><code${className}>${escapeHtml(body.join("\n"))}</code></pre>`);
+      blocks.push({ type: "code", language, text: body.join("\n") });
+      continue;
+    }
+    if (comments.closing === undefined && !inCode && /^(?: {4}|\t)/u.test(raw)) {
+      flushParagraph();
+      const body: string[] = [];
+      while (index < lines.length && /^(?: {4}|\t| *$)/u.test(lines[index] ?? "")) {
+        body.push((lines[index] ?? "").replace(/^(?: {4}|\t)/u, ""));
+        index += 1;
+      }
+      blocks.push({ type: "code", language: "", text: body.join("\n").replace(/\n+$/u, "") });
+      continue;
+    }
+    const rawDefinition = comments.closing === undefined && !inCode ? /^ {0,3}\[\^([^\]\n]*)\]:/u.exec(raw) : null;
+    if (rawDefinition !== null) {
+      flushParagraph();
+      const authored = [raw];
+      index += 1;
+      while (index < lines.length) {
+        const next = lines[index] ?? "";
+        if (/^(?: {4}|\t)/u.test(next) || (next.trim() === "" && /^(?: {4}|\t)/u.test(lines[index + 1] ?? ""))) {
+          authored.push(next);
+          index += 1;
+        } else {
+          break;
+        }
+      }
+      // Scan the full inline body together so comments inside a code span
+      // crossing continuation lines remain code, rather than disappearing.
+      const clean = withoutComments(authored.join("\n"), comments).split("\n");
+      const definition = /^ {0,3}\[\^([^\]\n]*)\]:[ \t]*(.*)$/u.exec(clean[0] ?? "");
+      if (!topLevel || definition === null) {
+        blocks.push({ type: "literal", text: clean.join("\n") });
+      } else {
+        const body = [definition[2] ?? "", ...clean.slice(1).map((line) => line.replace(/^(?: {4}|\t)/u, ""))];
+        blocks.push({ type: "footnote", note: admitFootnote(rawDefinition[1] ?? "", body, clean, footnotes) });
+      }
+      continue;
+    }
+    // Quoted blocks own their comment/code scope after removing the marker.
+    const line = comments.closing === undefined && !inCode && /^\s{0,3}>/u.test(raw)
+      ? raw
+      : withoutComments(raw, comments, paragraphBoundary(raw, lines[index + 1] ?? "")
+        ? undefined
+        : (ticks) => hasContinuedInlineCode(lines, index + 1, ticks));
+    if (inCode) {
+      paragraph.push(line);
+      index += 1;
       continue;
     }
-
-    // Blank line.
     if (line.trim() === "") {
       flushParagraph();
       index += 1;
       continue;
     }
-
-    // ATX heading.
     const heading = /^(#{1,6})\s+(.*)$/u.exec(line);
     if (heading !== null) {
       flushParagraph();
-      const level = (heading[1] ?? "#").length;
-      const body = renderInline((heading[2] ?? "").replace(/\s+#+$/u, ""), ctx);
-      const id = anchorId(stripMarkup(body), anchors);
-      html.push(`<h${level} id="${escapeAttribute(id)}">${body}</h${level}>`);
+      blocks.push({ type: "heading", level: (heading[1] ?? "#").length, text: (heading[2] ?? "").replace(/\s+#+$/u, "") });
       index += 1;
       continue;
     }
-
-    // Thematic break.
     if (/^\s{0,3}(?:\*\s*){3,}$/u.test(line) || /^\s{0,3}(?:-\s*){3,}$/u.test(line) || /^\s{0,3}(?:_\s*){3,}$/u.test(line)) {
       flushParagraph();
-      html.push("<hr>");
+      blocks.push({ type: "break" });
       index += 1;
       continue;
     }
-
-    // Blockquote (one level per pass; nesting via > > accumulation).
     if (/^\s{0,3}>/u.test(line)) {
       flushParagraph();
-      const quote: string[] = [];
+      const quote = [line.replace(/^\s{0,3}>\s?/u, "")];
+      index += 1;
       while (index < lines.length && /^\s{0,3}>/u.test(lines[index] ?? "")) {
         quote.push((lines[index] ?? "").replace(/^\s{0,3}>\s?/u, ""));
         index += 1;
       }
-      html.push(`<blockquote>${renderMarkdownToHtml(quote.join("\n"), ctx)}</blockquote>`);
+      blocks.push({ type: "quote", blocks: parseMarkdownBlocks(quote.join("\n"), footnotes, false) });
       continue;
     }
-
-    // Tables: header row, divider, body rows.
     if (line.includes("|") && index + 1 < lines.length && isTableDivider(lines[index + 1] ?? "")) {
       flushParagraph();
       const header = tableCells(line);
+      const rows: string[][] = [];
       index += 2;
-      const rows: string[] = [];
       while (index < lines.length && (lines[index] ?? "").includes("|") && (lines[index] ?? "").trim() !== "") {
-        rows.push(lines[index] ?? "");
+        const row = withoutComments(lines[index] ?? "", comments);
+        if (row.trim() !== "") rows.push(tableCells(row));
         index += 1;
       }
-      const head = header.map((cell) => `<th>${renderInline(cell, ctx)}</th>`).join("");
-      const bodyRows = rows.map((row) =>
-        `<tr>${tableCells(row).map((cell) => `<td>${renderInline(cell, ctx)}</td>`).join("")}</tr>`).join("");
-      html.push(`<table><thead><tr>${head}</tr></thead><tbody>${bodyRows}</tbody></table>`);
+      blocks.push({ type: "table", header, rows });
       continue;
     }
-
-    // Lists: flat scan with indent-based nesting.
     const marker = listMarker(line);
     if (marker !== undefined) {
       flushParagraph();
-      const items: string[] = [];
-      let ordered = marker.ordered;
+      const parts: ListPart[] = [];
       const baseIndent = marker.indent;
       const stack: { readonly indent: number; readonly ordered: boolean }[] = [];
+      let currentLine = line;
       while (index < lines.length) {
-        const current = listMarker(lines[index] ?? "");
-        const raw = lines[index] ?? "";
+        const current = listMarker(currentLine);
         if (current === undefined) {
-          if (raw.trim() === "") {
+          if (currentLine.trim() === "") {
             index += 1;
             break;
           }
-          const continuationIndent = raw.length - raw.trimStart().length;
-          if (items.length > 0 && continuationIndent > baseIndent) {
-            items.push(`\n${renderInline(raw.trim(), ctx)}`);
+          const continuationIndent = currentLine.length - currentLine.trimStart().length;
+          if (parts.length > 0 && continuationIndent > baseIndent) {
+            parts.push({ type: "continuation", text: currentLine.trim() });
             index += 1;
-            continue;
+          } else {
+            break;
           }
-          break;
-        }
-        const body = raw.slice(raw.search(/\S/u));
-        const itemBody = body.replace(/^(?:[-+*]|\d{1,9}[.)])\s+/u, "");
-        const task = /^\[([ xX])\]\s+/u.exec(itemBody);
-        const content = task === null ? itemBody : itemBody.slice((task[0] ?? "").length);
-        const checkbox = task === null
-          ? ""
-          : `<input type="checkbox" disabled${(task[1] ?? " ").toLowerCase() === "x" ? " checked" : ""}> `;
-        const top = stack[stack.length - 1];
-        if (current.indent > (top?.indent ?? baseIndent) && stack.length < 8) {
-          stack.push({ indent: current.indent, ordered: current.ordered });
-          items.push(`<${current.ordered ? "ol" : "ul"}>`);
-        }
-        while (stack.length > 0 && current.indent < (stack[stack.length - 1]?.indent ?? baseIndent)) {
-          const popped = stack.pop();
-          items.push(`</${popped?.ordered === true ? "ol" : "ul"}>`);
+        } else {
+          const body = currentLine.slice(currentLine.search(/\S/u));
+          const itemBody = body.replace(/^(?:[-+*]|\d{1,9}[.)])\s+/u, "");
+          const task = /^\[([ xX])\]\s+/u.exec(itemBody);
+          const text = task === null ? itemBody : itemBody.slice((task[0] ?? "").length);
+          if (current.indent > (stack[stack.length - 1]?.indent ?? baseIndent) && stack.length < 8) {
+            stack.push({ indent: current.indent, ordered: current.ordered });
+            parts.push({ type: "open", ordered: current.ordered });
+          }
+          while (stack.length > 0 && current.indent < (stack[stack.length - 1]?.indent ?? baseIndent)) {
+            parts.push({ type: "close", ordered: stack.pop()?.ordered === true });
+          }
+          parts.push({ type: "item", text, ...(task === null ? {} : { checked: (task[1] ?? " ").toLowerCase() === "x" }) });
+          index += 1;
         }
-        items.push(`<li>${checkbox}${renderInline(content, ctx)}</li>`);
-        index += 1;
-      }
-      while (stack.length > 0) {
-        const popped = stack.pop();
-        items.push(`</${popped?.ordered === true ? "ol" : "ul"}>`);
+        // Do not consume comments on a line that belongs to the next block.
+        const next = lines[index] ?? "";
+        if (listMarker(next) === undefined && next.trim() !== "" && next.length - next.trimStart().length <= baseIndent) break;
+        currentLine = withoutComments(next, comments);
       }
-      html.push(`<${ordered ? "ol" : "ul"}>${items.join("")}</${ordered ? "ol" : "ul"}>`);
-      continue;
-    }
-
-    // HTML comment open.
-    const commentStart = line.indexOf("<!--");
-    if (commentStart !== -1) {
-      const close = line.indexOf("-->", commentStart + 4);
-      if (close === -1) inComment = true;
-      index += 1;
+      while (stack.length > 0) parts.push({ type: "close", ordered: stack.pop()?.ordered === true });
+      blocks.push({ type: "list", ordered: marker.ordered, parts });
       continue;
     }
+    paragraph.push(line);
+    index += 1;
+  }
+  flushParagraph();
+  return blocks;
+}
 
-    // Indented code.
-    if (/^(?: {4}|\t)/u.test(line)) {
-      flushParagraph();
-      const body: string[] = [];
-      while (index < lines.length && /^(?: {4}|\t| *$)/u.test(lines[index] ?? "")) {
-        body.push((lines[index] ?? "").replace(/^(?: {4}|\t)/u, ""));
-        index += 1;
+function renderBlocks(blocks: readonly MarkdownBlock[], ctx: PublishRenderContext, footnotes: Footnotes, anchors: Map<string, number>): string {
+  return blocks.map((block): string => {
+    switch (block.type) {
+      case "paragraph": return `<p>${renderInline(block.text, ctx, footnotes)}</p>`;
+      case "literal": return `<p>${escapeHtml(block.text).replaceAll("\n", "<br>")}</p>`;
+      case "heading": {
+        const body = renderInline(block.text, ctx, footnotes);
+        return `<h${block.level} id="${escapeAttribute(anchorId(stripMarkup(body), anchors))}">${body}</h${block.level}>`;
       }
-      html.push(`<pre><code>${escapeHtml(body.join("\n").replace(/\n+$/u, ""))}</code></pre>`);
-      continue;
+      case "code": return `<pre><code${block.language === "" ? "" : ` class="language-${escapeAttribute(block.language)}"`}>${escapeHtml(block.text)}</code></pre>`;
+      case "break": return "<hr>";
+      case "quote": return `<blockquote>${renderBlocks(block.blocks, ctx, footnotes, anchors)}</blockquote>`;
+      case "table": {
+        const header = block.header.map((cell) => `<th>${renderInline(cell, ctx, footnotes)}</th>`).join("");
+        const rows = block.rows.map((row) => `<tr>${row.map((cell) => `<td>${renderInline(cell, ctx, footnotes)}</td>`).join("")}</tr>`).join("");
+        return `<table><thead><tr>${header}</tr></thead><tbody>${rows}</tbody></table>`;
+      }
+      case "list": {
+        const parts = block.parts.map((part) => {
+          switch (part.type) {
+            case "open": return `<${part.ordered ? "ol" : "ul"}>`;
+            case "close": return `</${part.ordered ? "ol" : "ul"}>`;
+            case "continuation": return `\n${renderInline(part.text, ctx, footnotes)}`;
+            case "item": return `<li>${part.checked === undefined ? "" : `<input type="checkbox" disabled${part.checked ? " checked" : ""}> `}${renderInline(part.text, ctx, footnotes)}</li>`;
+          }
+        }).join("");
+        return `<${block.ordered ? "ol" : "ul"}>${parts}</${block.ordered ? "ol" : "ul"}>`;
+      }
+      case "footnote": return footnotes.disabled || block.note.invalid
+        ? `<p class="unresolved footnote-definition">${escapeHtml(block.note.authored).replaceAll("\n", "<br>")}</p>`
+        : "";
     }
+  }).filter((html) => html !== "").join("\n");
+}
 
-    paragraph.push(line);
-    index += 1;
+/** Render authored Markdown to a sanitized HTML fragment. */
+export function renderMarkdownToHtml(content: string, ctx: PublishRenderContext): string {
+  const footnotes: Footnotes = { byLabel: new Map(), numbered: [], definitions: 0, references: 0, disabled: false };
+  const blocks = parseMarkdownBlocks(content, footnotes, true);
+  const body = renderBlocks(blocks, ctx, footnotes, new Map());
+  if (footnotes.disabled) return body;
+  // Keep unreferenced authored definitions visible after referenced notes.
+  for (const note of footnotes.byLabel.values()) {
+    if (note !== null && !note.invalid) footnoteNumber(note, footnotes);
   }
-  flushParagraph();
-  return html.join("\n");
+  if (footnotes.numbered.length === 0) return body;
+  const notes = footnotes.numbered.map((note) => {
+    const number = note.number;
+    const backlinks = note.references.map((id, index) => `<a href="#${id}" role="doc-backlink" aria-label="Back to reference ${index + 1} for footnote ${number}">↩ ${index + 1}</a>`).join(" ");
+    // Definitions are inline prose. Footnote syntax inside them stays literal,
+    // so cycles cannot expand and every backlink corresponds to authored prose.
+    const text = renderInline(note.body.replaceAll("\n", " "), ctx);
+    return `<li id="wordcell:footnote:${number}" tabindex="-1">${text}${backlinks === "" ? "" : ` ${backlinks}`}</li>`;
+  }).join("\n");
+  return `${body}${body === "" ? "" : "\n"}<section class="footnotes" aria-label="Footnotes"><ol>\n${notes}\n</ol></section>`;
+}
+
+export type PublishMarkdownText = {
+  readonly text: string;
+  readonly preview: string;
+};
+
+/**
+ * Readable display text, derived before truncation or case normalization.
+ * Shares the article grammar and footnote admission rules; it is not an index
+ * or a replacement for authored Markdown. Valid citation navigation disappears,
+ * while unresolved definitions/references, escaped text, and code stay literal.
+ */
+export function projectMarkdownText(content: string, description?: string): PublishMarkdownText {
+  const footnotes: Footnotes = { byLabel: new Map(), numbered: [], definitions: 0, references: 0, disabled: false, plain: true };
+  const blocks = parseMarkdownBlocks(content, footnotes, true);
+  // Display labels need no filesystem, URL fetch, or selected-note resolution.
+  // Unresolved local assets retain their authored alt text through renderInline.
+  const context: PublishRenderContext = {
+    source: "", resolveNote: () => undefined, resolveAsset: () => undefined, noteHref: () => "",
+  };
+  const inline = (text: string, state?: Footnotes): string => stripMarkup(renderInline(text, context, state));
+  const parts = (items: readonly MarkdownBlock[], state: Footnotes): string[] => items.map((block): string => {
+    switch (block.type) {
+      case "paragraph": case "heading": return inline(block.text, state);
+      case "literal": case "code": return block.text;
+      case "break": return "";
+      case "quote": return parts(block.blocks, state).join("\n\n");
+      case "table": return [block.header, ...block.rows].map((row) => row.map((cell) => inline(cell, state)).join(" ")).join("\n");
+      case "list": return block.parts.map((part) => part.type === "item" || part.type === "continuation" ? inline(part.text, state) : "").filter(Boolean).join("\n");
+      case "footnote": return state.disabled || block.note.invalid ? block.note.authored : "";
+    }
+  });
+  const rendered = parts(blocks, footnotes);
+  // The article orders valid definitions by first reference, then unreferenced
+  // definitions. Nested references in their bodies deliberately remain literal.
+  if (!footnotes.disabled) for (const note of footnotes.byLabel.values()) {
+    if (note !== null && !note.invalid) footnoteNumber(note, footnotes);
+  }
+  const text = [...rendered, ...footnotes.numbered.map((note) => inline(note.body.replaceAll("\n", " ")))].filter(Boolean).join("\n\n");
+  let preview = rendered.find((value, index) => blocks[index]?.type === "paragraph" && value.trim() !== "") ?? text;
+  if (description !== undefined && description.trim() !== "") {
+    // Resolve description citations against the same authored definitions, but
+    // never let preview rendering consume the article's citation allowance.
+    const state: Footnotes = {
+      byLabel: new Map([...footnotes.byLabel].map(([label, note]) => [label, note === null ? null : { body: note.body, authored: note.authored, invalid: note.invalid, references: [] }])),
+      numbered: [], definitions: footnotes.definitions, references: 0, disabled: footnotes.disabled, plain: true,
+    };
+    const authored = parts(parseMarkdownBlocks(description, state, false), state).filter(Boolean).join("\n\n");
+    if (authored.trim() !== "") preview = authored;
+  }
+  return { text, preview };
 }
 
 export function stripMarkup(html: string): string {