Support conditional content for llms-txt format

Allow users to include/exclude content in .llms.md output using
content-visible/content-hidden with when-format="llms-txt". A pre-filter
intercepts ConditionalBlock nodes before they are cleared, wrapping them
in marker divs that llms.lua and the HTML finalizer handle independently.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cscheid

src/project/types/website/website-llms.ts

@@ -8,7 +8,7 @@ import { basename, join, relative } from "../../../deno_ral/path.ts";
 import { existsSync } from "../../../deno_ral/fs.ts";
 import { pathWithForwardSlashes } from "../../../core/path.ts";
 
-import { Document, Element } from "../../../core/deno-dom.ts";
+import { Document, Element, Node } from "../../../core/deno-dom.ts";
 import { execProcess } from "../../../core/process.ts";
 import { pandocBinaryPath, resourcePath } from "../../../core/resources.ts";
 
@@ -83,9 +83,36 @@ export function llmsHtmlFinalizer(
 
     // Convert HTML to markdown using Pandoc with the llms.lua filter
     await convertHtmlToLlmsMarkdown(htmlContent, llmsOutputPath);
+
+    // Clean up conditional content markers from the original HTML doc
+    cleanupConditionalContent(doc);
   };
 }
 
+/**
+ * Clean up conditional content markers from the HTML document.
+ * - Remove llms-only content (should not appear in HTML output)
+ * - Unwrap llms-hidden markers (keep content, remove wrapper div)
+ */
+function cleanupConditionalContent(doc: Document): void {
+  // Remove llms-only content from HTML output
+  for (const el of doc.querySelectorAll(".llms-conditional-content")) {
+    (el as Element).remove();
+  }
+
+  // Unwrap llms-hidden markers (keep content, remove wrapper div)
+  for (const el of doc.querySelectorAll(".llms-hidden-content")) {
+    const parent = (el as Element).parentElement;
+    if (parent) {
+      const element = el as Element;
+      while (element.firstChild) {
+        parent.insertBefore(element.firstChild as Node, element as Node);
+      }
+      element.remove();
+    }
+  }
+}
+
 /**
  * Extract the main content from an HTML document, removing navigation,
  * sidebars, footers, scripts, and styles.

src/resources/filters/llms/llms.lua

@@ -15,6 +15,7 @@ local skippable_classes = {
     ["quarto-float"] = true,
     ["quarto-float-fig"] = true,
     ["figure"] = true,
+    ["llms-conditional-content"] = true,
 }
 local droppable_classes = {
     ["navbar-container"] = true,
@@ -26,6 +27,7 @@ local droppable_classes = {
     ["quarto-listing-category"] = true,  -- category filter sidebar
     ["listing-category"] = true,  -- individual category badges
     ["quarto-page-breadcrumbs"] = true,  -- breadcrumb navigation
+    ["llms-hidden-content"] = true,
 }
 local droppable_ids = {
     ["quarto-header"] = true,

src/resources/filters/main.lua

@@ -144,6 +144,7 @@ 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/llms-conditional-content.lua")
 import("./quarto-pre/code-filename.lua")
 import("./quarto-pre/contentsshortcode.lua")
 import("./quarto-pre/engine-escape.lua")
@@ -322,6 +323,15 @@ local quarto_pre_filters = {
     traverser = 'jog',
   },
 
+  { name = "pre-llms-conditional-content",
+    filter = filterIf(
+      function() return param("llms-txt", false) end,
+      llms_resolve_conditional_content()
+    ),
+    flags = { "has_conditional_content" },
+    traverser = 'jog',
+  },
+
   { name = "pre-combined-hidden",
     filter = combineFilters({
       hidden(),

src/resources/filters/quarto-pre/llms-conditional-content.lua

@@ -0,0 +1,57 @@
+-- llms-conditional-content.lua
+-- Copyright (C) 2020-2026 Posit Software, PBC
+--
+-- Pre-filter that intercepts ConditionalBlock nodes referencing llms-txt
+-- and replaces them with marker Divs so content can be included/excluded
+-- from llms.md output independently of the HTML format.
+-- Only runs when llms-txt is enabled (guarded by filterIf in main.lua).
+
+local constants = require("modules/constants")
+
+local function list_contains(list, value)
+  if not list then return false end
+  for _, v in ipairs(list) do
+    if v == value then return true end
+  end
+  return false
+end
+
+-- Determine if a ConditionalBlock should be visible for llms-txt output.
+-- Returns true (include), false (exclude), or nil (no llms-txt condition).
+local function is_llms_visible(tbl)
+  local cond = tbl.condition
+  local has_when = list_contains(cond[constants.kWhenFormat], "llms-txt")
+  local has_unless = list_contains(cond[constants.kUnlessFormat], "llms-txt")
+
+  if not has_when and not has_unless then return nil end
+
+  if tbl.behavior == constants.kContentVisible then
+    -- content-visible when-format="llms-txt" -> include for llms
+    -- content-visible unless-format="llms-txt" -> exclude for llms
+    return has_when
+  else -- content-hidden
+    -- content-hidden when-format="llms-txt" -> exclude for llms
+    -- content-hidden unless-format="llms-txt" -> include for llms
+    return has_unless
+  end
+end
+
+function llms_resolve_conditional_content()
+  return {
+    ConditionalBlock = function(tbl)
+      local llms_visible = is_llms_visible(tbl)
+      if llms_visible == nil then return nil end
+
+      local html_visible = is_visible(tbl)  -- from content-hidden.lua
+      if llms_visible == html_visible then return nil end  -- no intervention needed
+
+      local div = tbl.original_node:clone()
+      if llms_visible then
+        div.classes:insert("llms-conditional-content")
+      else
+        div.classes:insert("llms-hidden-content")
+      end
+      return div
+    end
+  }
+end

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 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"]
+        # First array: patterns that MUST match - verify anchor links, code annotations, and conditional content
+        - ["\\[callout examples\\]\\(about\\.llms\\.md#callout-examples\\)", "#<1>", "#<2>", "Load tidyverse", "Open help for ggplot", "only for LLM consumption"]
+        # Second array: patterns that must NOT match (no .html links, no annotation UI, no hidden content)
+        - ["\\.html\\)", "\\.html#", "code-annotation-anchor", "should not appear in LLM output"]
 ---
 
 ## Test Content
@@ -26,6 +26,16 @@ See the [about page](about.qmd) for more information.
 
 Also see the [callout examples](about.qmd#callout-examples).
 
+## Conditional Content
+
+::: {.content-visible when-format="llms-txt"}
+This content is only for LLM consumption.
+:::
+
+::: {.content-hidden when-format="llms-txt"}
+This content should not appear in LLM output.
+:::
+
 ## Code Annotations
 
 ```r