Preserve code annotations in llms-txt output

cscheid · claude · cscheid · commit 29cc6c4b511a · 2026-02-19T13:12:53.000-06:00
Save original code block text (with annotation markers) before
code-annotation.lua strips them, then restore during HTML-to-markdown
conversion. Annotation definition lists are converted to ordered lists.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/src/project/types/website/website-llms.ts b/src/project/types/website/website-llms.ts
@@ -128,6 +128,9 @@ function extractMainContent(doc: Document): string {
     return "";
   }
 
+  // Preprocess annotated code blocks before converting to markdown
+  preprocessAnnotatedCodeBlocks(clone, main as Element);
+
   // Return a minimal HTML document with just the content
   return `<!DOCTYPE html>
 <html>
@@ -138,6 +141,65 @@ ${main.innerHTML}
 </html>`;
 }
 
+/**
+ * Preprocess annotated code blocks for llms output.
+ * Restores original code text (with annotation markers) and converts
+ * the annotation definition list to an ordered list.
+ */
+function preprocessAnnotatedCodeBlocks(doc: Document, container: Element): void {
+  // Restore original code text in annotated code blocks.
+  // The llms-code-annotations.lua filter saves the original text
+  // (before code-annotation.lua strips markers) as a data attribute.
+  const annotated = container.querySelectorAll("[data-llms-code-original]");
+  for (const node of annotated) {
+    const el = node as Element;
+    const originalText = el.getAttribute("data-llms-code-original");
+    if (!originalText) continue;
+
+    // The attribute is on the wrapper div; find the <code> element inside
+    const codeEl = el.tagName === "CODE"
+      ? el
+      : el.querySelector("code") as Element | null;
+    if (codeEl) {
+      // Replace content with original (removes syntax highlighting spans + annotation buttons)
+      codeEl.textContent = originalText;
+    }
+
+    el.removeAttribute("data-llms-code-original");
+  }
+
+  // Remove annotation gutter elements
+  const gutters = container.querySelectorAll(
+    ".code-annotation-gutter, .code-annotation-gutter-bg",
+  );
+  for (const gutter of gutters) {
+    (gutter as Element).remove();
+  }
+
+  // Convert annotation definition lists to ordered lists.
+  // The annotation text is in <dd> elements; <dt> elements have just the number.
+  const dls = container.querySelectorAll("dl.code-annotation-container-grid");
+  for (const dlNode of dls) {
+    const dl = dlNode as Element;
+    const ol = doc.createElement("ol");
+    const dds = dl.querySelectorAll("dd");
+    for (const ddNode of dds) {
+      const dd = ddNode as Element;
+      const li = doc.createElement("li");
+      li.innerHTML = dd.innerHTML;
+      ol.appendChild(li);
+    }
+
+    // Replace the DL (and its cell-annotation wrapper div if present)
+    const parent = dl.parentElement;
+    if (parent && parent.classList.contains("cell-annotation")) {
+      parent.parentElement?.replaceChild(ol, parent);
+    } else {
+      dl.parentElement?.replaceChild(ol, dl);
+    }
+  }
+}
+
 /**
  * Convert HTML content to markdown using Pandoc with the llms.lua filter.
  */
diff --git a/src/project/types/website/website.ts b/src/project/types/website/website.ts
@@ -32,6 +32,7 @@ import { projectOffset, projectOutputDir } from "../../project-shared.ts";
 import { isHtmlFileOutput } from "../../../config/format.ts";
 
 import {
+  kFilterParams,
   kIncludeInHeader,
   kPageTitle,
   kTitle,
@@ -358,6 +359,8 @@ export const websiteProjectType: ProjectType = {
 
     // Add llms.txt finalizer if enabled
     if (websiteConfigBoolean(kLlmsTxt, false, project.config)) {
+      extras[kFilterParams] = extras[kFilterParams] || {};
+      extras[kFilterParams]["llms-txt"] = true;
       extras.html[kHtmlFinalizers]?.push(
         llmsHtmlFinalizer(source, project, format),
       );
diff --git a/src/resources/filters/main.lua b/src/resources/filters/main.lua
@@ -143,6 +143,7 @@ import("./quarto-pre/bibliography-formats.lua")
 import("./quarto-pre/book-links.lua")
 import("./quarto-pre/book-numbering.lua")
 import("./quarto-pre/code-annotation.lua")
+import("./quarto-pre/llms-code-annotations.lua")
 import("./quarto-pre/code-filename.lua")
 import("./quarto-pre/contentsshortcode.lua")
 import("./quarto-pre/engine-escape.lua")
@@ -336,6 +337,15 @@ local quarto_pre_filters = {
     traverser = 'jog',
   },
 
+  { name = "pre-llms-save-code-annotations",
+    filter = filterIf(
+      function() return param("llms-txt", false) end,
+      llms_save_code_annotations()
+    ),
+    flags = { "has_code_annotations" },
+    traverser = 'jog',
+  },
+
   { name = "pre-code-annotations",
     filter = code_annotations(),
     flags = { "has_code_annotations" },
diff --git a/src/resources/filters/quarto-pre/llms-code-annotations.lua b/src/resources/filters/quarto-pre/llms-code-annotations.lua
@@ -0,0 +1,16 @@
+-- llms-code-annotations.lua
+-- Copyright (C) 2020-2026 Posit Software, PBC
+--
+-- Saves original CodeBlock text before code-annotation.lua strips markers.
+-- Only runs when llms-txt is enabled (guarded by filterIf in main.lua).
+
+function llms_save_code_annotations()
+  return {
+    CodeBlock = function(el)
+      if el.text:match("<%d+>") then
+        el.attributes["data-llms-code-original"] = el.text
+      end
+      return el
+    end
+  }
+end
diff --git a/tests/docs/smoke-all/website/llms-txt/index.qmd b/tests/docs/smoke-all/website/llms-txt/index.qmd
@@ -12,10 +12,10 @@ _quarto:
         # Second array: patterns that must NOT match (empty)
         - []
       ensureLlmsMdRegexMatches:
-        # First array: patterns that MUST match - verify anchor links are converted
-        - ["\\[callout examples\\]\\(about\\.llms\\.md#callout-examples\\)"]
-        # Second array: patterns that must NOT match (no .html or .html# links)
-        - ["\\.html\\)", "\\.html#"]
+        # First array: patterns that MUST match - verify anchor links and code annotations
+        - ["\\[callout examples\\]\\(about\\.llms\\.md#callout-examples\\)", "#<1>", "#<2>", "Load tidyverse", "Open help for ggplot"]
+        # Second array: patterns that must NOT match (no .html links, no annotation UI)
+        - ["\\.html\\)", "\\.html#", "code-annotation-anchor"]
 ---
 
 ## Test Content
@@ -25,3 +25,12 @@ This is a test website for the llms-txt feature.
 See the [about page](about.qmd) for more information.
 
 Also see the [callout examples](about.qmd#callout-examples).
+
+## Code Annotations
+
+```r
+library(tidyverse) # <1>
+?ggplot # <2>
+```
+1. Load tidyverse
+2. Open help for ggplot
