From 0bbbb7ceb496b87f84f78aac96b55ac76c633362 Mon Sep 17 00:00:00 2001
From: zedoraps <philip@moesli.net>
Date: Thu, 4 Jun 2026 12:45:44 +0200
Subject: [PATCH 1/4] Add copy-as-Markdown action to documentation pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a copy-for-LLM button and "View page as markdown" / "Use in
your agent" dropdown to every documentation page. The button copies the
page's Markdown twin to the clipboard; the menu links open the same
content for human or agent consumption.

Decouple the per-page `.md` route from the `LLMS_TXT` env flag via a
new plugin option, so the action works in normal dev and production
builds. The site-wide `/llms.txt` and `/llms-full.txt` routes stay
gated behind the flag.

Add a shared `markdownPathForDocPath` / `markdownUrlForDocPath`
helper so the per-page route, the copy URL in PageTitle, and link
rewriting in entry-to-markdown agree on slug normalization (`*/index`
→ `*`).

Move changelog topics behind an `import.meta.glob` loader so the
per-page route survives fresh checkouts where the generated
`sidebar-changelog.generated.ts` is absent.

Assisted-by: Claude Opus 4.7 (Claude Code)
---
 astro.config.mjs                              |  24 +-
 src/components/PageTitle.astro                | 708 +++++++++++++++++-
 .../starlight-llms-txt/changelog-topics.ts    |  16 +
 .../starlight-llms-txt/entry-to-markdown.ts   |   3 +-
 src/plugins/starlight-llms-txt/index.ts       |  36 +-
 .../routes/page-markdown.ts                   |  32 +-
 .../starlight-llms-txt/sitemap-generator.ts   |   7 +-
 src/plugins/starlight-llms-txt/types.ts       |   9 +
 src/utils/llm-markdown-path.ts                |  20 +
 9 files changed, 802 insertions(+), 53 deletions(-)
 create mode 100644 src/plugins/starlight-llms-txt/changelog-topics.ts
 create mode 100644 src/utils/llm-markdown-path.ts

diff --git a/astro.config.mjs b/astro.config.mjs
index 00de01b0e..f20159a39 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -162,20 +162,16 @@ export default defineConfig({
         },
       },
       plugins: [
-        ...(llmsTxt
-          ? [
-              starlightLlmsTxt({
-                projectName: "Tenzir",
-                description:
-                  "The low-code data pipeline solution for security teams",
-                perPageMarkdown: {
-                  extensionStrategy: "replace",
-                },
-                sitemapAlias: true,
-                preambles: true,
-              }),
-            ]
-          : []),
+        starlightLlmsTxt({
+          llmsTxt,
+          projectName: "Tenzir",
+          description: "The low-code data pipeline solution for security teams",
+          perPageMarkdown: {
+            extensionStrategy: "replace",
+          },
+          sitemapAlias: llmsTxt,
+          preambles: llmsTxt,
+        }),
         ...(checkLinks
           ? [
               starlightLinksValidator({
diff --git a/src/components/PageTitle.astro b/src/components/PageTitle.astro
index 9a9bd2c1e..cd60fe90a 100644
--- a/src/components/PageTitle.astro
+++ b/src/components/PageTitle.astro
@@ -1,6 +1,6 @@
 ---
-import type { Props } from "@astrojs/starlight/props";
 import { pathWithBase } from "@utils/base";
+import { markdownPathForDocPath } from "@utils/llm-markdown-path";
 import { formatSlug, getDocsMap } from "@utils/page-title";
 import { getSearchWeight } from "../search-weights";
 
@@ -24,6 +24,12 @@ const { starlightRoute } = Astro.locals;
 const weightConfig = getSearchWeight(starlightRoute.id);
 const pagefindType = weightConfig?.metadata?.type;
 const pagefindWeight = weightConfig?.weight;
+const markdownUrl = pathWithBase(
+  markdownPathForDocPath(starlightRoute.entry.id),
+);
+const agentSkillsGuideUrl = pathWithBase(
+  "/guides/ai-workbench/use-agent-skills/",
+);
 
 // Build h1 attributes
 const h1Attrs: Record<string, any> = {
@@ -168,24 +174,700 @@ for (let i = 0; i < segments.length; i++) {
       </ol>
     </nav>
   )}
-  <h1 {...h1Attrs}>
-    {starlightRoute.entry.data.title}
-  </h1>
+  <div class="page-heading-row">
+    <h1 {...h1Attrs}>
+      {starlightRoute.entry.data.title}
+    </h1>
+    <div class="page-actions" data-page-actions>
+      <button
+        type="button"
+        class="copy-for-llm"
+        data-copy-for-llm
+        data-copy-label="copy for LLM"
+        data-markdown-url={markdownUrl}
+        aria-label="copy for LLM"
+        title="copy for LLM"
+        disabled
+      >
+        <svg
+          aria-hidden="true"
+          class="copy-for-llm__icon"
+          xmlns="http://www.w3.org/2000/svg"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect>
+          <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path>
+        </svg>
+        <span class="copy-for-llm__label" data-copy-for-llm-label>copy for LLM</span>
+        <span class="copy-for-llm__status" data-copy-for-llm-status aria-live="polite"></span>
+      </button>
+      <button
+        type="button"
+        class="page-actions__dropdown-trigger"
+        data-page-actions-toggle
+        aria-label="More page actions"
+        aria-haspopup="menu"
+        aria-expanded="false"
+        aria-controls="page-actions-menu"
+      >
+        <svg
+          aria-hidden="true"
+          class="page-actions__chevron"
+          xmlns="http://www.w3.org/2000/svg"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <path d="m6 9 6 6 6-6"></path>
+        </svg>
+      </button>
+      <div
+        id="page-actions-menu"
+        class="page-actions__menu"
+        data-page-actions-menu
+        role="menu"
+        hidden
+      >
+        <a
+          class="page-actions__menu-item"
+          href={markdownUrl}
+          role="menuitem"
+          target="_blank"
+          rel="noopener noreferrer"
+          aria-label="View page as markdown in a new tab"
+        >
+          <svg
+            aria-hidden="true"
+            class="page-actions__menu-icon"
+            xmlns="http://www.w3.org/2000/svg"
+            width="16"
+            height="16"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"></path>
+            <path d="M14 2v4a2 2 0 0 0 2 2h4"></path>
+            <path d="M10 9H8"></path>
+            <path d="M16 13H8"></path>
+            <path d="M16 17H8"></path>
+          </svg>
+          <span>View page as markdown</span>
+        </a>
+        <a
+          class="page-actions__menu-item"
+          href={agentSkillsGuideUrl}
+          role="menuitem"
+        >
+          <svg
+            aria-hidden="true"
+            class="page-actions__menu-icon"
+            xmlns="http://www.w3.org/2000/svg"
+            width="16"
+            height="16"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <path d="M12 8V4H8"></path>
+            <rect width="16" height="12" x="4" y="8" rx="2"></rect>
+            <path d="M2 14h2"></path>
+            <path d="M20 14h2"></path>
+            <path d="M15 13v2"></path>
+            <path d="M9 13v2"></path>
+          </svg>
+          <span>Use in your agent</span>
+        </a>
+      </div>
+    </div>
+  </div>
 </div>
 
+<script>
+  const copiedMarkdownByUrl = new Map<string, string>();
+  const markdownRequestsByUrl = new Map<string, Promise<string>>();
+
+  function fetchMarkdown(markdownUrl: string): Promise<string> {
+    const cachedMarkdown = copiedMarkdownByUrl.get(markdownUrl);
+    if (cachedMarkdown) {
+      return Promise.resolve(cachedMarkdown);
+    }
+
+    const pendingRequest = markdownRequestsByUrl.get(markdownUrl);
+    if (pendingRequest) {
+      return pendingRequest;
+    }
+
+    const request = fetch(markdownUrl, {
+      headers: { Accept: "text/plain" },
+    })
+      .then((response) => {
+        if (!response.ok) {
+          throw new Error(`Failed to fetch ${markdownUrl}`);
+        }
+        return response.text();
+      })
+      .then((markdown) => {
+        copiedMarkdownByUrl.set(markdownUrl, markdown);
+        return markdown;
+      })
+      .finally(() => {
+        markdownRequestsByUrl.delete(markdownUrl);
+      });
+
+    markdownRequestsByUrl.set(markdownUrl, request);
+    return request;
+  }
+
+  async function copyTextToClipboard(text: string): Promise<void> {
+    if (navigator.clipboard?.writeText && window.isSecureContext) {
+      await navigator.clipboard.writeText(text);
+      return;
+    }
+
+    const textarea = document.createElement("textarea");
+    textarea.value = text;
+    textarea.setAttribute("readonly", "");
+    textarea.style.position = "fixed";
+    textarea.style.insetBlockStart = "-100vh";
+    document.body.append(textarea);
+    textarea.select();
+
+    try {
+      if (!document.execCommand("copy")) {
+        throw new Error("copy command failed");
+      }
+    } finally {
+      textarea.remove();
+    }
+  }
+
+  function canWriteClipboardItem(): boolean {
+    return (
+      window.isSecureContext &&
+      typeof ClipboardItem !== "undefined" &&
+      typeof navigator.clipboard?.write === "function"
+    );
+  }
+
+  function writeMarkdownWithClipboardItem(markdownUrl: string): Promise<void> {
+    const markdownBlob = fetchMarkdown(markdownUrl).then(
+      (markdown) => new Blob([markdown], { type: "text/plain" }),
+    );
+    const item = new ClipboardItem({ "text/plain": markdownBlob });
+    return navigator.clipboard.write([item]);
+  }
+
+  function setCopyButtonState(
+    button: HTMLButtonElement,
+    state: "idle" | "pending" | "success" | "error",
+    label: string,
+    status: string,
+  ) {
+    button.dataset.copyState = state;
+    button.disabled = state === "pending";
+
+    const labelElement = button.querySelector("[data-copy-for-llm-label]");
+    if (labelElement) {
+      labelElement.textContent = label;
+    }
+
+    const statusElement = button.querySelector("[data-copy-for-llm-status]");
+    if (statusElement) {
+      statusElement.textContent = status;
+    }
+  }
+
+  document.addEventListener("click", async (event) => {
+    if (!(event.target instanceof Element)) {
+      return;
+    }
+
+    const button = event.target.closest<HTMLButtonElement>(
+      "button[data-copy-for-llm]",
+    );
+    if (!button) {
+      return;
+    }
+
+    const markdownUrl = button.dataset.markdownUrl;
+    const idleLabel = button.dataset.copyLabel ?? "Copy for LLM";
+    if (!markdownUrl) {
+      return;
+    }
+
+    setCopyButtonState(button, "pending", "Copying", "");
+
+    try {
+      const cachedMarkdown = copiedMarkdownByUrl.get(markdownUrl);
+      if (cachedMarkdown) {
+        await copyTextToClipboard(cachedMarkdown);
+      } else if (canWriteClipboardItem()) {
+        await writeMarkdownWithClipboardItem(markdownUrl);
+      } else {
+        const markdown = await fetchMarkdown(markdownUrl);
+        await copyTextToClipboard(markdown);
+      }
+
+      setCopyButtonState(
+        button,
+        "success",
+        "Copied",
+        "Copied page Markdown to clipboard.",
+      );
+    } catch {
+      setCopyButtonState(
+        button,
+        "error",
+        "Failed",
+        "Could not copy page Markdown.",
+      );
+    } finally {
+      window.setTimeout(() => {
+        setCopyButtonState(button, "idle", idleLabel, "");
+      }, 2000);
+    }
+  });
+
+  function preloadCopyButton(button: HTMLButtonElement) {
+    const markdownUrl = button.dataset.markdownUrl;
+    if (!markdownUrl) {
+      return;
+    }
+
+    const idleLabel = button.dataset.copyLabel ?? "Copy for LLM";
+    setCopyButtonState(
+      button,
+      "pending",
+      idleLabel,
+      "Preparing page Markdown.",
+    );
+    fetchMarkdown(markdownUrl)
+      .then(() => {
+        setCopyButtonState(button, "idle", idleLabel, "");
+      })
+      .catch(() => {
+        setCopyButtonState(button, "idle", idleLabel, "");
+      });
+  }
+
+  for (const button of document.querySelectorAll<HTMLButtonElement>(
+    "button[data-copy-for-llm]",
+  )) {
+    preloadCopyButton(button);
+  }
+
+  document.addEventListener("pointerover", (event) => {
+    if (!(event.target instanceof Element)) {
+      return;
+    }
+
+    const button = event.target.closest<HTMLButtonElement>(
+      "button[data-copy-for-llm]",
+    );
+    const markdownUrl = button?.dataset.markdownUrl;
+    if (markdownUrl) {
+      fetchMarkdown(markdownUrl).catch(() => {});
+    }
+  });
+
+  document.addEventListener("focusin", (event) => {
+    if (!(event.target instanceof Element)) {
+      return;
+    }
+
+    const button = event.target.closest<HTMLButtonElement>(
+      "button[data-copy-for-llm]",
+    );
+    const markdownUrl = button?.dataset.markdownUrl;
+    if (markdownUrl) {
+      fetchMarkdown(markdownUrl).catch(() => {});
+    }
+  });
+
+  function closePageActionsMenu(actions: HTMLElement) {
+    const toggle = actions.querySelector<HTMLButtonElement>(
+      "[data-page-actions-toggle]",
+    );
+    const menu = actions.querySelector<HTMLElement>("[data-page-actions-menu]");
+    if (!toggle || !menu) {
+      return;
+    }
+
+    toggle.setAttribute("aria-expanded", "false");
+    actions.dataset.menuState = "closed";
+    menu.hidden = true;
+  }
+
+  function openPageActionsMenu(actions: HTMLElement) {
+    const toggle = actions.querySelector<HTMLButtonElement>(
+      "[data-page-actions-toggle]",
+    );
+    const menu = actions.querySelector<HTMLElement>("[data-page-actions-menu]");
+    if (!toggle || !menu) {
+      return;
+    }
+
+    toggle.setAttribute("aria-expanded", "true");
+    actions.dataset.menuState = "open";
+    menu.hidden = false;
+  }
+
+  function closeOtherPageActionsMenus(actions: HTMLElement) {
+    for (const openActions of document.querySelectorAll<HTMLElement>(
+      '[data-page-actions][data-menu-state="open"]',
+    )) {
+      if (openActions !== actions) {
+        closePageActionsMenu(openActions);
+      }
+    }
+  }
+
+  document.addEventListener("click", (event) => {
+    if (!(event.target instanceof Element)) {
+      return;
+    }
+
+    const toggle = event.target.closest<HTMLButtonElement>(
+      "[data-page-actions-toggle]",
+    );
+    if (toggle) {
+      const actions = toggle.closest<HTMLElement>("[data-page-actions]");
+      if (!actions) {
+        return;
+      }
+
+      const isOpen = toggle.getAttribute("aria-expanded") === "true";
+      closeOtherPageActionsMenus(actions);
+      if (isOpen) {
+        closePageActionsMenu(actions);
+      } else {
+        openPageActionsMenu(actions);
+      }
+      return;
+    }
+
+    const menu = event.target.closest<HTMLElement>("[data-page-actions-menu]");
+    for (const openActions of document.querySelectorAll<HTMLElement>(
+      '[data-page-actions][data-menu-state="open"]',
+    )) {
+      if (!menu || !openActions.contains(menu)) {
+        closePageActionsMenu(openActions);
+      }
+    }
+  });
+
+  document.addEventListener("keydown", (event) => {
+    if (!(event.target instanceof Element)) {
+      return;
+    }
+
+    if (event.key === "Escape") {
+      const focusedActions =
+        document.activeElement instanceof Element
+          ? document.activeElement.closest<HTMLElement>("[data-page-actions]")
+          : null;
+
+      for (const openActions of document.querySelectorAll<HTMLElement>(
+        '[data-page-actions][data-menu-state="open"]',
+      )) {
+        closePageActionsMenu(openActions);
+      }
+
+      focusedActions
+        ?.querySelector<HTMLButtonElement>("[data-page-actions-toggle]")
+        ?.focus();
+      return;
+    }
+
+    if (event.key !== "ArrowDown") {
+      return;
+    }
+
+    const toggle = event.target.closest<HTMLButtonElement>(
+      "[data-page-actions-toggle]",
+    );
+    const actions = toggle?.closest<HTMLElement>("[data-page-actions]");
+    if (!actions) {
+      return;
+    }
+
+    event.preventDefault();
+    closeOtherPageActionsMenus(actions);
+    openPageActionsMenu(actions);
+    actions
+      .querySelector<HTMLElement>('[data-page-actions-menu] [role="menuitem"]')
+      ?.focus();
+  });
+</script>
+
 <style>
   .page-title-with-breadcrumbs {
     display: contents;
   }
 
+  .page-heading-row {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--tnz-space-4);
+    margin-top: var(--tnz-space-3);
+  }
+
   /* Page title h1 styles */
   h1 {
-    margin-top: var(--tnz-space-3);
+    flex: 1;
+    min-width: 0;
+    margin-top: 0;
     font-size: var(--sl-text-h1);
     line-height: var(--sl-line-height-headings);
     font-weight: var(--tnz-font-semibold);
     color: var(--sl-color-white);
-    letter-spacing: -0.02em;
+    letter-spacing: 0;
+  }
+
+  .page-actions {
+    flex: none;
+    position: relative;
+    display: inline-flex;
+    align-items: stretch;
+    height: var(--tnz-button-height-s);
+    border: 1px solid var(--tnz-neutral-600);
+    border-radius: var(--tnz-radius);
+    background-color: color-mix(in srgb, var(--tnz-neutral-700) 24%, transparent);
+    color: var(--tnz-neutral-400);
+    transition:
+      background-color var(--tnz-transition-base),
+      border-color var(--tnz-transition-base),
+      color var(--tnz-transition-base);
+  }
+
+  .page-actions:hover,
+  .page-actions:focus-within,
+  .page-actions[data-menu-state="open"] {
+    border-color: var(--tnz-neutral-500);
+    background-color: color-mix(in srgb, var(--tnz-neutral-600) 22%, transparent);
+    color: var(--tnz-neutral-200);
+  }
+
+  .page-actions[data-menu-state="open"] .copy-for-llm,
+  .page-actions[data-menu-state="open"] .page-actions__dropdown-trigger {
+    background-color: color-mix(in srgb, var(--tnz-neutral-600) 22%, transparent);
+    color: var(--tnz-neutral-200);
+  }
+
+  .copy-for-llm,
+  .page-actions__dropdown-trigger {
+    appearance: none;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    height: 100%;
+    padding: 0;
+    border: 0;
+    background: transparent;
+    color: inherit;
+    cursor: pointer;
+    transition:
+      background-color var(--tnz-transition-base),
+      color var(--tnz-transition-base);
+  }
+
+  .copy-for-llm {
+    width: 28px;
+    border-start-start-radius: calc(var(--tnz-radius) - 1px);
+    border-end-start-radius: calc(var(--tnz-radius) - 1px);
+    border-inline-end: 1px solid var(--tnz-neutral-600);
+  }
+
+  .page-actions__dropdown-trigger {
+    width: 28px;
+    border-start-end-radius: calc(var(--tnz-radius) - 1px);
+    border-end-end-radius: calc(var(--tnz-radius) - 1px);
+  }
+
+  .copy-for-llm:hover,
+  .copy-for-llm:focus-visible,
+  .page-actions__dropdown-trigger:hover,
+  .page-actions__dropdown-trigger:focus-visible,
+  .copy-for-llm:active,
+  .page-actions__dropdown-trigger:active,
+  .page-actions__dropdown-trigger[aria-expanded="true"] {
+    background-color: color-mix(in srgb, var(--tnz-neutral-600) 42%, transparent);
+    color: var(--tnz-neutral-50);
+  }
+
+  .copy-for-llm:focus-visible,
+  .page-actions__dropdown-trigger:focus-visible {
+    box-shadow:
+      0 0 0 1px var(--tnz-neutral-200),
+      0 0 0 4px var(--tnz-neutral-250);
+    outline: none;
+  }
+
+  .copy-for-llm:disabled {
+    cursor: progress;
+    opacity: 0.72;
+  }
+
+  .copy-for-llm[data-copy-state="success"] {
+    background-color: color-mix(in srgb, var(--tnz-green-500) 14%, transparent);
+    color: color-mix(in srgb, var(--tnz-green-200) 82%, var(--tnz-neutral-50));
+  }
+
+  .copy-for-llm[data-copy-state="error"] {
+    background-color: color-mix(in srgb, var(--tnz-red-500) 14%, transparent);
+    color: color-mix(in srgb, var(--tnz-red-200) 82%, var(--tnz-neutral-50));
+  }
+
+  .copy-for-llm__icon,
+  .page-actions__chevron,
+  .page-actions__menu-icon {
+    width: 16px;
+    height: 16px;
+    flex: none;
+  }
+
+  .page-actions__chevron {
+    transition: transform var(--tnz-transition-base);
+  }
+
+  .page-actions__dropdown-trigger[aria-expanded="true"] .page-actions__chevron {
+    transform: rotate(180deg);
+  }
+
+  .copy-for-llm__label,
+  .copy-for-llm__status {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  .page-actions__menu {
+    position: absolute;
+    z-index: var(--tnz-z-dropdown);
+    inset-block-start: calc(100% + var(--tnz-space-1));
+    inset-inline-end: 0;
+    min-width: 12.5rem;
+    padding: var(--tnz-space-1);
+    border: 1px solid var(--tnz-neutral-600);
+    border-radius: var(--tnz-radius);
+    background-color: var(--tnz-neutral-700);
+    box-shadow: 0 12px 28px rgb(0 0 0 / 0.28);
+  }
+
+  .page-actions__menu[hidden] {
+    display: none;
+  }
+
+  .page-actions__menu-item,
+  .page-actions__menu-item:link,
+  .page-actions__menu-item:visited {
+    display: flex;
+    align-items: center;
+    gap: var(--tnz-space-2);
+    min-height: var(--tnz-button-height-m);
+    padding: var(--tnz-space-1) var(--tnz-space-2);
+    border: 0;
+    border-radius: var(--tnz-radius-sm);
+    color: var(--tnz-neutral-200);
+    font-size: var(--tnz-text-sm);
+    line-height: var(--tnz-leading-sm);
+    font-weight: var(--tnz-font-medium);
+    text-decoration: none;
+    white-space: nowrap;
+    transition:
+      background-color var(--tnz-transition-base),
+      color var(--tnz-transition-base);
+  }
+
+  .page-actions__menu-item:hover,
+  .page-actions__menu-item:focus-visible {
+    background-color: var(--tnz-neutral-600);
+    color: var(--tnz-neutral-50);
+    text-decoration: none;
+    outline: none;
+  }
+
+  :root[data-theme='light'] .page-actions {
+    border-color: var(--tnz-neutral-250);
+    background-color: var(--tnz-neutral-50);
+    color: var(--tnz-neutral-800);
+  }
+
+  :root[data-theme='light'] .page-actions:hover,
+  :root[data-theme='light'] .page-actions:focus-within,
+  :root[data-theme='light'] .page-actions[data-menu-state="open"] {
+    border-color: var(--tnz-neutral-300);
+    background-color: var(--tnz-neutral-100);
+    color: var(--tnz-neutral-800);
+  }
+
+  :root[data-theme='light'] .copy-for-llm {
+    border-inline-end-color: var(--tnz-neutral-250);
+  }
+
+  :root[data-theme='light'] .copy-for-llm:hover,
+  :root[data-theme='light'] .copy-for-llm:focus-visible,
+  :root[data-theme='light'] .page-actions__dropdown-trigger:hover,
+  :root[data-theme='light'] .page-actions__dropdown-trigger:focus-visible,
+  :root[data-theme='light'] .copy-for-llm:active,
+  :root[data-theme='light'] .page-actions__dropdown-trigger:active,
+  :root[data-theme='light'] .page-actions__dropdown-trigger[aria-expanded="true"] {
+    background-color: var(--tnz-neutral-200);
+    color: var(--tnz-neutral-800);
+  }
+
+  :root[data-theme='light'] .copy-for-llm[data-copy-state="success"] {
+    background-color: color-mix(in srgb, var(--tnz-green-500) 10%, var(--tnz-neutral-50));
+    color: var(--tnz-green-600);
+  }
+
+  :root[data-theme='light'] .copy-for-llm[data-copy-state="error"] {
+    background-color: color-mix(in srgb, var(--tnz-red-500) 10%, var(--tnz-neutral-50));
+    color: var(--tnz-red-600);
+  }
+
+  :root[data-theme='light'] .page-actions__menu {
+    border-color: var(--tnz-neutral-250);
+    background-color: var(--tnz-neutral-50);
+    box-shadow: 0 12px 28px rgb(14 16 23 / 0.12);
+  }
+
+  :root[data-theme='light'] .page-actions__menu-item,
+  :root[data-theme='light'] .page-actions__menu-item:link,
+  :root[data-theme='light'] .page-actions__menu-item:visited {
+    color: var(--tnz-neutral-700);
+  }
+
+  :root[data-theme='light'] .page-actions__menu-item:hover,
+  :root[data-theme='light'] .page-actions__menu-item:focus-visible {
+    background-color: var(--tnz-neutral-100);
+    color: var(--tnz-neutral-800);
   }
 
   /* Breadcrumb Component Styles */
@@ -294,10 +976,22 @@ for (let i = 0; i < segments.length; i++) {
   }
 
   @media (max-width: 50rem) {
-    h1 {
+    .page-heading-row {
+      flex-direction: column;
+      align-items: flex-start;
+      gap: var(--tnz-space-2);
       margin-top: var(--tnz-space-2);
     }
 
+    .page-actions {
+      margin-top: 0;
+    }
+
+    .page-actions__menu {
+      inset-inline-start: 0;
+      inset-inline-end: auto;
+    }
+
     .c-breadcrumbs {
       font-size: var(--tnz-text-sm);
       margin-bottom: var(--tnz-space-3);
diff --git a/src/plugins/starlight-llms-txt/changelog-topics.ts b/src/plugins/starlight-llms-txt/changelog-topics.ts
new file mode 100644
index 000000000..11dfb6eee
--- /dev/null
+++ b/src/plugins/starlight-llms-txt/changelog-topics.ts
@@ -0,0 +1,16 @@
+export interface ChangelogTopic {
+  label: string;
+  link?: string;
+}
+
+interface ChangelogModule {
+  changelogTopics: ChangelogTopic[];
+}
+
+const modules = import.meta.glob<ChangelogModule>(
+  "../../sidebar-changelog.generated.ts",
+  { eager: true },
+);
+
+export const changelogTopics: ChangelogTopic[] =
+  Object.values(modules)[0]?.changelogTopics ?? [];
diff --git a/src/plugins/starlight-llms-txt/entry-to-markdown.ts b/src/plugins/starlight-llms-txt/entry-to-markdown.ts
index 2f1bc6460..5c30130ab 100644
--- a/src/plugins/starlight-llms-txt/entry-to-markdown.ts
+++ b/src/plugins/starlight-llms-txt/entry-to-markdown.ts
@@ -10,6 +10,7 @@ import remarkStringify from "remark-stringify";
 import { unified } from "unified";
 import { remove } from "unist-util-remove";
 import { visit } from "unist-util-visit";
+import { markdownPathForDocPath } from "../../utils/llm-markdown-path";
 import { getNonMarkdownPaths } from "../../utils/redirects.mjs";
 
 const astroContainer = await experimental_AstroContainer.create({
@@ -196,7 +197,7 @@ const htmlToMarkdownPipeline = unified()
         const suffix = href.slice(suffixIndex);
         // Remove trailing slash before adding .md
         const cleanPath = path.endsWith("/") ? path.slice(0, -1) : path;
-        link.properties.href = `${cleanPath}.md${suffix}`;
+        link.properties.href = `${markdownPathForDocPath(cleanPath)}${suffix}`;
       }
     };
   })
diff --git a/src/plugins/starlight-llms-txt/index.ts b/src/plugins/starlight-llms-txt/index.ts
index b3ab49050..a79773862 100644
--- a/src/plugins/starlight-llms-txt/index.ts
+++ b/src/plugins/starlight-llms-txt/index.ts
@@ -19,21 +19,25 @@ export default function starlightLlmsTxt(
           name: "starlight-llms-txt",
           hooks: {
             "astro:config:setup"({ injectRoute, updateConfig }) {
-              // /llms.txt - The sitemap entry point with navigation, descriptions, and headings
-              injectRoute({
-                entrypoint: new URL("./routes/llms.txt.ts", import.meta.url),
-                pattern: "/llms.txt",
-                prerender: true,
-              });
-              // /llms-full.txt - Complete documentation bundle
-              injectRoute({
-                entrypoint: new URL(
-                  "./routes/llms-full.txt.ts",
-                  import.meta.url,
-                ),
-                pattern: "/llms-full.txt",
-                prerender: true,
-              });
+              const llmsTxtRoutesEnabled = opts.llmsTxt ?? true;
+
+              if (llmsTxtRoutesEnabled) {
+                // /llms.txt - The sitemap entry point with navigation, descriptions, and headings
+                injectRoute({
+                  entrypoint: new URL("./routes/llms.txt.ts", import.meta.url),
+                  pattern: "/llms.txt",
+                  prerender: true,
+                });
+                // /llms-full.txt - Complete documentation bundle
+                injectRoute({
+                  entrypoint: new URL(
+                    "./routes/llms-full.txt.ts",
+                    import.meta.url,
+                  ),
+                  pattern: "/llms-full.txt",
+                  prerender: true,
+                });
+              }
 
               // Parse perPageMarkdown config
               const perPageMarkdownConfig = (() => {
@@ -72,7 +76,7 @@ export default function starlightLlmsTxt(
               }
 
               // Inject sitemap.md alias if enabled (serves same content as llms.txt)
-              if (opts.sitemapAlias) {
+              if (llmsTxtRoutesEnabled && opts.sitemapAlias) {
                 injectRoute({
                   entrypoint: new URL("./routes/llms.txt.ts", import.meta.url),
                   pattern: "/sitemap.md",
diff --git a/src/plugins/starlight-llms-txt/routes/page-markdown.ts b/src/plugins/starlight-llms-txt/routes/page-markdown.ts
index 0cab44601..b6f308d1d 100644
--- a/src/plugins/starlight-llms-txt/routes/page-markdown.ts
+++ b/src/plugins/starlight-llms-txt/routes/page-markdown.ts
@@ -16,7 +16,11 @@ import {
   reference,
   tutorials,
 } from "../../../sidebar";
-import { changelogTopics } from "../../../sidebar-changelog.generated";
+import {
+  markdownUrlForDocPath,
+  normalizeDocPathForMarkdown,
+} from "../../../utils/llm-markdown-path";
+import { changelogTopics } from "../changelog-topics";
 import { entryToSimpleMarkdown } from "../entry-to-markdown";
 import type { SidebarItem } from "../types";
 import { ensureTrailingSlash, isDefaultLocale } from "../utils";
@@ -39,6 +43,8 @@ interface ChildLink {
  * Extract child links from a sidebar section for a given doc ID.
  */
 function extractChildLinks(docId: string, baseUrl: string): ChildLink[] | null {
+  const childUrl = (docPath: string) => markdownUrlForDocPath(baseUrl, docPath);
+
   // Check if we're looking for a top-level section
   if (docId in SECTION_SIDEBARS) {
     const sidebarItems = SECTION_SIDEBARS[docId];
@@ -48,17 +54,17 @@ function extractChildLinks(docId: string, baseUrl: string): ChildLink[] | null {
           const label = item.split("/").pop() || item;
           return {
             title: label.charAt(0).toUpperCase() + label.slice(1),
-            url: `${baseUrl}/${item}.md`,
+            url: childUrl(item),
           };
         } else if (item.link) {
-          return { title: item.label, url: `${baseUrl}/${item.link}.md` };
+          return { title: item.label, url: childUrl(item.link) };
         } else if (item.items && item.items.length > 0) {
           // For groups, link to the first item if it's an index page
           const first = item.items[0];
           if (typeof first === "string") {
-            return { title: item.label, url: `${baseUrl}/${first}.md` };
+            return { title: item.label, url: childUrl(first) };
           } else if (first && "link" in first && first.link) {
-            return { title: item.label, url: `${baseUrl}/${first.link}.md` };
+            return { title: item.label, url: childUrl(first.link) };
           }
           return null;
         }
@@ -74,7 +80,7 @@ function extractChildLinks(docId: string, baseUrl: string): ChildLink[] | null {
     );
     return projects.map((t) => ({
       title: t.label,
-      url: `${baseUrl}/${t.link}.md`,
+      url: childUrl(t.link),
     }));
   }
 
@@ -95,6 +101,8 @@ function findChildrenForPath(
   targetPath: string,
   baseUrl: string,
 ): ChildLink[] | null {
+  const childUrl = (docPath: string) => markdownUrlForDocPath(baseUrl, docPath);
+
   for (const item of items) {
     if (typeof item === "string") continue;
     if (!item.items) continue;
@@ -117,16 +125,16 @@ function findChildrenForPath(
             const label = child.split("/").pop() || child;
             return {
               title: label.charAt(0).toUpperCase() + label.slice(1),
-              url: `${baseUrl}/${child}.md`,
+              url: childUrl(child),
             };
           } else if (child.link) {
-            return { title: child.label, url: `${baseUrl}/${child.link}.md` };
+            return { title: child.label, url: childUrl(child.link) };
           } else if (child.items && child.items.length > 0) {
             const first = child.items[0];
             if (typeof first === "string") {
-              return { title: child.label, url: `${baseUrl}/${first}.md` };
+              return { title: child.label, url: childUrl(first) };
             } else if (first && "link" in first && first.link) {
-              return { title: child.label, url: `${baseUrl}/${first.link}.md` };
+              return { title: child.label, url: childUrl(first.link) };
             }
           }
           return null;
@@ -147,7 +155,7 @@ function findChildrenForPath(
  */
 function getChildLinksForPage(docId: string, baseUrl: string): ChildLink[] {
   // Normalize the doc ID (remove /index suffix)
-  const normalizedId = docId.replace(/\/index$/, "");
+  const normalizedId = normalizeDocPathForMarkdown(docId);
 
   const children = extractChildLinks(normalizedId, baseUrl);
   return children || [];
@@ -179,7 +187,7 @@ export const getStaticPaths = (async () => {
       // Simple .md replacement pattern
       return [
         {
-          params: { slug },
+          params: { slug: normalizeDocPathForMarkdown(slug) },
           props: { doc },
         },
       ];
diff --git a/src/plugins/starlight-llms-txt/sitemap-generator.ts b/src/plugins/starlight-llms-txt/sitemap-generator.ts
index bed328538..ea0c7f869 100644
--- a/src/plugins/starlight-llms-txt/sitemap-generator.ts
+++ b/src/plugins/starlight-llms-txt/sitemap-generator.ts
@@ -10,8 +10,9 @@ import {
   reference,
   tutorials,
 } from "../../sidebar";
+import { markdownUrlForDocPath } from "../../utils/llm-markdown-path";
 // Changelog topics
-import { changelogTopics } from "../../sidebar-changelog.generated";
+import { changelogTopics } from "./changelog-topics";
 import { entryToSimpleMarkdown } from "./entry-to-markdown";
 import { extractDescription } from "./excerpt-utils";
 import type { SidebarItem } from "./types";
@@ -119,7 +120,7 @@ async function resolveDocEntry(
     title: doc.data.title,
     description: extractDescription(markdown),
     headings: isReferenceOnly ? [] : extractHeadings(markdown),
-    url: `${baseUrl}/${docPath}.md`,
+    url: markdownUrlForDocPath(baseUrl, doc.id),
   };
 }
 
@@ -331,7 +332,7 @@ function formatChangelogSection(baseUrl: string): string {
   const projects = changelogTopics.filter((t) => t.label !== "Timeline");
 
   for (const project of projects) {
-    output += `- [${project.label}](${baseUrl}/${project.link}.md)\n`;
+    output += `- [${project.label}](${markdownUrlForDocPath(baseUrl, project.link)})\n`;
   }
 
   output += "\n";
diff --git a/src/plugins/starlight-llms-txt/types.ts b/src/plugins/starlight-llms-txt/types.ts
index 49c72a7fc..619773524 100644
--- a/src/plugins/starlight-llms-txt/types.ts
+++ b/src/plugins/starlight-llms-txt/types.ts
@@ -29,6 +29,15 @@ export type SidebarItem =
 
 /** Plugin user options. */
 export interface StarlightLlmsTxtOptions {
+  /**
+   * Generate the global LLM routes (`/llms.txt` and `/llms-full.txt`).
+   *
+   * Per-page Markdown routes remain controlled by `perPageMarkdown`.
+   *
+   * @default true
+   */
+  llmsTxt?: boolean;
+
   /**
    * Provide a custom name for this project or software. This will be used in `llms.txt` to identify
    * what the documentation is for.
diff --git a/src/utils/llm-markdown-path.ts b/src/utils/llm-markdown-path.ts
new file mode 100644
index 000000000..c991ff1fe
--- /dev/null
+++ b/src/utils/llm-markdown-path.ts
@@ -0,0 +1,20 @@
+export function normalizeDocPathForMarkdown(path: string): string {
+  const normalizedPath = path.replace(/^\/+|\/+$/g, "");
+
+  if (!normalizedPath || normalizedPath === "index") {
+    return "index";
+  }
+
+  return normalizedPath.replace(/\/index$/, "");
+}
+
+export function markdownPathForDocPath(docPath: string): string {
+  return `/${normalizeDocPathForMarkdown(docPath)}.md`;
+}
+
+export function markdownUrlForDocPath(
+  baseUrl: string,
+  docPath: string,
+): string {
+  return `${baseUrl}${markdownPathForDocPath(docPath)}`;
+}

From b1a2a6a7e45bc169fd51ed7a263944ff90753ded Mon Sep 17 00:00:00 2001
From: zedoraps <philip@moesli.net>
Date: Thu, 4 Jun 2026 12:55:19 +0200
Subject: [PATCH 2/4] Hide Markdown actions on pages without a Markdown twin

OpenAPI pages (`/reference/{node,platform}/api/...`) render via
PageTitle but are not part of the `docs` content collection, so the
plugin generates no `.md` route for them. Clicking the copy or view
button would 404.

Gate the action buttons on `docsMap.has(starlightRoute.entry.id)` so
they only appear on pages backed by the collection. Future
integrations that inject pages outside the collection are covered by
the same check.

Assisted-by: Claude Opus 4.7 (Claude Code)
---
 src/components/PageTitle.astro | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/components/PageTitle.astro b/src/components/PageTitle.astro
index cd60fe90a..6a8917777 100644
--- a/src/components/PageTitle.astro
+++ b/src/components/PageTitle.astro
@@ -24,6 +24,10 @@ const { starlightRoute } = Astro.locals;
 const weightConfig = getSearchWeight(starlightRoute.id);
 const pagefindType = weightConfig?.metadata?.type;
 const pagefindWeight = weightConfig?.weight;
+// The per-page Markdown twin only exists for pages backed by the `docs`
+// content collection. Pages injected by other integrations (e.g. starlight-
+// openapi) have no `.md` route, so we hide the action buttons there.
+const hasMarkdownTwin = docsMap.has(starlightRoute.entry.id);
 const markdownUrl = pathWithBase(
   markdownPathForDocPath(starlightRoute.entry.id),
 );
@@ -178,6 +182,7 @@ for (let i = 0; i < segments.length; i++) {
     <h1 {...h1Attrs}>
       {starlightRoute.entry.data.title}
     </h1>
+    {hasMarkdownTwin && (
     <div class="page-actions" data-page-actions>
       <button
         type="button"
@@ -298,6 +303,7 @@ for (let i = 0; i < segments.length; i++) {
         </a>
       </div>
     </div>
+    )}
   </div>
 </div>
 

From 19841e5a076f7bd4f4701cbc76ea98e15805342a Mon Sep 17 00:00:00 2001
From: zedoraps <philip@moesli.net>
Date: Thu, 4 Jun 2026 13:08:11 +0200
Subject: [PATCH 3/4] Stop prefetching page Markdown on every page load

The button JS used to fire a fetch for the page's Markdown twin on
every page load and kept the copy button disabled until the response
arrived. Most readers never use the copy action, so this was one extra
page-sized request per view, and on slow links the action was
unavailable until the prefetch settled.

Flip the SSR-disabled buttons to idle on JS init without fetching. The
existing pointerover and focusin listeners already prefetch on user
intent, and the click handler fetches inline when the cache is empty.

Assisted-by: Claude Opus 4.7 (Claude Code)
---
 src/components/PageTitle.astro | 29 ++++++-----------------------
 1 file changed, 6 insertions(+), 23 deletions(-)

diff --git a/src/components/PageTitle.astro b/src/components/PageTitle.astro
index 6a8917777..4610cd046 100644
--- a/src/components/PageTitle.astro
+++ b/src/components/PageTitle.astro
@@ -453,32 +453,15 @@ for (let i = 0; i < segments.length; i++) {
     }
   });
 
-  function preloadCopyButton(button: HTMLButtonElement) {
-    const markdownUrl = button.dataset.markdownUrl;
-    if (!markdownUrl) {
-      return;
-    }
-
-    const idleLabel = button.dataset.copyLabel ?? "Copy for LLM";
-    setCopyButtonState(
-      button,
-      "pending",
-      idleLabel,
-      "Preparing page Markdown.",
-    );
-    fetchMarkdown(markdownUrl)
-      .then(() => {
-        setCopyButtonState(button, "idle", idleLabel, "");
-      })
-      .catch(() => {
-        setCopyButtonState(button, "idle", idleLabel, "");
-      });
-  }
-
+  // Enable the buttons on JS init without fetching. The SSR markup ships
+  // them disabled so non-JS readers see a no-op control. The pointerover
+  // and focusin listeners below prefetch on intent, and the click handler
+  // falls back to fetching inline if nothing is cached.
   for (const button of document.querySelectorAll<HTMLButtonElement>(
     "button[data-copy-for-llm]",
   )) {
-    preloadCopyButton(button);
+    const idleLabel = button.dataset.copyLabel ?? "Copy for LLM";
+    setCopyButtonState(button, "idle", idleLabel, "");
   }
 
   document.addEventListener("pointerover", (event) => {

From 02d7a9b2d3f9fc2b420d4659b96009237161cce3 Mon Sep 17 00:00:00 2001
From: zedoraps <philip@moesli.net>
Date: Fri, 5 Jun 2026 21:25:03 +0200
Subject: [PATCH 4/4] Emit absolute URLs in per-page Markdown output

Internal links in the generated `.md` were root-relative
(`/foo.md`) while the appended `## Contents` section was absolute
(`https://docs.tenzir.com/foo.md`). The mismatch was awkward and the
relative form was the wrong default: an LLM or agent reading a copied
page has no origin to resolve `/foo.md` against.

Wrap the rehype/remark pipeline in a per-baseUrl factory with a small
cache, and have the link rewriter prepend the site URL. Non-markdown
internal paths (redirects like `/discord`, OpenAPI roots) are
absolutised too without appending `.md`.

Assisted-by: Claude Opus 4.7 (Claude Code)
---
 .../starlight-llms-txt/entry-to-markdown.ts   | 377 ++++++++++--------
 1 file changed, 207 insertions(+), 170 deletions(-)

diff --git a/src/plugins/starlight-llms-txt/entry-to-markdown.ts b/src/plugins/starlight-llms-txt/entry-to-markdown.ts
index 5c30130ab..05bf9494a 100644
--- a/src/plugins/starlight-llms-txt/entry-to-markdown.ts
+++ b/src/plugins/starlight-llms-txt/entry-to-markdown.ts
@@ -1,4 +1,5 @@
 import { type CollectionEntry, render } from "astro:content";
+import { starlightLlmsTxtContext } from "virtual:starlight-llms-txt/context";
 import mdxServer from "@astrojs/mdx/server.js";
 import type { APIContext } from "astro";
 import { experimental_AstroContainer } from "astro/container";
@@ -10,179 +11,51 @@ import remarkStringify from "remark-stringify";
 import { unified } from "unified";
 import { remove } from "unist-util-remove";
 import { visit } from "unist-util-visit";
-import { markdownPathForDocPath } from "../../utils/llm-markdown-path";
+import { markdownUrlForDocPath } from "../../utils/llm-markdown-path";
 import { getNonMarkdownPaths } from "../../utils/redirects.mjs";
+import { ensureTrailingSlash } from "./utils";
 
 const astroContainer = await experimental_AstroContainer.create({
   renderers: [{ name: "astro:jsx", ssr: mdxServer }],
 });
 
-const htmlToMarkdownPipeline = unified()
-  .use(rehypeParse, { fragment: true })
-  .use(function improveExpressiveCodeHandling() {
-    return (tree) => {
-      const ecInstances = selectAll(
-        ".expressive-code",
-        tree as Parameters<typeof selectAll>[1],
-      );
-      for (const instance of ecInstances) {
-        // Remove the "Terminal Window" label from Expressive Code terminal frames.
-        const figcaption = select("figcaption", instance);
-        if (figcaption) {
-          const terminalWindowTextIndex = figcaption.children.findIndex(
-            (child) => matches("span.sr-only", child),
-          );
-          if (terminalWindowTextIndex > -1) {
-            figcaption.children.splice(terminalWindowTextIndex, 1);
-          }
-        }
-        const pre = select("pre", instance);
-        const code = select("code", instance);
-        // Use Expressive Code's `data-language=*` attribute to set a `language-*` class name.
-        // This is what `hast-util-to-mdast` checks for code language metadata.
-        if (pre?.properties.dataLanguage && code) {
-          if (!Array.isArray(code.properties.className))
-            code.properties.className = [];
+/**
+ * Rewrite internal `<a>` hrefs to absolute URLs, appending `.md` for routes
+ * that have a Markdown twin. Absolute URLs are the right choice because the
+ * generated `.md` is intended for LLMs / agents that may have no origin
+ * context to resolve a root-relative path against.
+ */
+function absolutizeInternalLinks(baseUrl: string) {
+  const skipExtensions =
+    /\.(md|txt|xml|json|yaml|yml|html|png|jpg|jpeg|gif|svg|pdf|zip|tar|gz)$/i;
+  const nonMarkdownPaths = getNonMarkdownPaths();
 
-          const diffLines =
-            pre.properties.dataLanguage === "diff"
-              ? []
-              : code.children.filter((child) =>
-                  matches("div.ec-line.ins, div.ec-line.del", child),
-                );
-          if (diffLines.length === 0) {
-            code.properties.className.push(
-              `language-${pre.properties.dataLanguage}`,
-            );
-          } else {
-            code.properties.className.push("language-diff");
-            for (const line of diffLines) {
-              if (line.type !== "element") continue;
-              const classes = line.properties?.className;
-              if (typeof classes !== "string" && !Array.isArray(classes))
-                continue;
-              const marker = classes.includes("ins") ? "+" : "-";
-              const span = select("span:not(.indent)", line);
-              const firstChild = span?.children[0];
-              if (firstChild?.type === "text") {
-                firstChild.value = `${marker}${firstChild.value}`;
-              }
-            }
-          }
-        }
-      }
-    };
-  })
-  .use(function improveTabsHandling() {
-    return (tree) => {
-      const tabInstances = selectAll(
-        "starlight-tabs",
-        tree as Parameters<typeof selectAll>[1],
-      );
-      for (const instance of tabInstances) {
-        const tabs = selectAll('[role="tab"]', instance);
-        const panels = selectAll('[role="tabpanel"]', instance);
-        // Convert parent `<starlight-tabs>` element to empty unordered list.
-        instance.tagName = "ul";
-        instance.properties = {};
-        instance.children = [];
-        // Iterate over tabs and panels to build a list with tab label as initial list text.
-        for (let i = 0; i < Math.min(tabs.length, panels.length); i++) {
-          const tab = tabs[i];
-          const panel = panels[i];
-          if (!tab || !panel) continue;
-          // Filter out extra whitespace and icons from tab contents.
-          const tabLabel = tab.children
-            .filter((child) => child.type === "text" && child.value.trim())
-            .map((child) => child.type === "text" && child.value.trim())
-            .join("");
-          // Add list entry for this tab and panel.
-          instance.children.push({
-            type: "element",
-            tagName: "li",
-            properties: {},
-            children: [
-              {
-                type: "element",
-                tagName: "p",
-                children: [{ type: "text", value: tabLabel }],
-                properties: {},
-              },
-              panel,
-            ],
-          });
-        }
-      }
-    };
-  })
-  .use(function improveFileTreeHandling() {
-    return (tree) => {
-      const trees = selectAll(
-        "starlight-file-tree",
-        tree as Parameters<typeof selectAll>[1],
-      );
-      for (const fileTree of trees) {
-        // Remove "Directory" screen reader labels from <FileTree> entries.
-        remove(fileTree, (_node) => {
-          const node = _node as Parameters<typeof matches>[1];
-          return matches(".sr-only", node);
-        });
-      }
-    };
-  })
-  .use(function removeHeadingAnchorLinks() {
-    return (tree) => {
-      // Remove Starlight's heading anchor links (e.g. "Section titled …").
-      // These are sibling <a> elements next to headings inside .sl-heading-wrapper divs.
-      remove(tree, (_node) => {
-        const node = _node as Parameters<typeof matches>[1];
-        return matches("a.sl-anchor-link", node);
-      });
-    };
-  })
-  .use(function removeInlineSemanticIcons() {
-    return (tree) => {
-      // Remove decorative semantic-reference icons such as the `fn` badge shown
-      // before links rendered by components like <Fn> and <Op>. In the markdown
-      // bundle, these should serialize as plain links only.
-      // The icons live inside `.semantic-link` anchors as `.inline-icon` children.
-      visit(tree, "element", (node: any) => {
-        if (!matches("a.semantic-link", node)) return;
-        node.children = node.children.filter(
-          (child: any) => !matches(".inline-icon", child),
-        );
-      });
-    };
-  })
-  .use(function addMarkdownExtensionToInternalLinks() {
-    // Extensions that should not get .md appended
-    const skipExtensions =
-      /\.(md|txt|xml|json|yaml|yml|html|png|jpg|jpeg|gif|svg|pdf|zip|tar|gz)$/i;
-    // Routes that have no markdown page (redirects, OpenAPI-generated)
-    const nonMarkdownPaths = getNonMarkdownPaths();
-    return (tree) => {
+  return function rewriteLinks() {
+    return (tree: unknown) => {
       const links = selectAll("a", tree as Parameters<typeof selectAll>[1]);
       for (const link of links) {
         const href = link.properties?.href;
         if (typeof href !== "string") continue;
-        // Only transform internal links (starting with /)
-        if (!href.startsWith("/")) continue;
-        // Skip routes without markdown pages
+        // Only transform internal links (starting with /); skip anchor-only.
+        if (!href.startsWith("/") || href.startsWith("/#")) continue;
+
         const pathPart = href.split("#")[0].split("?")[0];
-        if (
-          nonMarkdownPaths.some(
-            (r) =>
-              pathPart === r ||
-              pathPart === `${r}/` ||
-              pathPart.startsWith(`${r}/`),
-          )
-        )
+
+        // Routes without a Markdown twin (redirects, OpenAPI): absolutise
+        // but do not append `.md`.
+        const isNonMarkdown = nonMarkdownPaths.some(
+          (r) =>
+            pathPart === r ||
+            pathPart === `${r}/` ||
+            pathPart.startsWith(`${r}/`),
+        );
+        if (isNonMarkdown || skipExtensions.test(pathPart)) {
+          link.properties.href = `${baseUrl}${href}`;
           continue;
-        // Skip if already has a known extension
-        if (skipExtensions.test(pathPart)) continue;
-        // Skip anchor-only links
-        if (href.startsWith("/#")) continue;
-        // Add .md extension (preserve hash and query if present)
+        }
+
+        // Internal doc page: absolutise and append `.md` while preserving
+        // hash and query.
         const hashIndex = href.indexOf("#");
         const queryIndex = href.indexOf("?");
         const suffixIndex =
@@ -195,18 +68,181 @@ const htmlToMarkdownPipeline = unified()
                 : href.length;
         const path = href.slice(0, suffixIndex);
         const suffix = href.slice(suffixIndex);
-        // Remove trailing slash before adding .md
         const cleanPath = path.endsWith("/") ? path.slice(0, -1) : path;
-        link.properties.href = `${markdownPathForDocPath(cleanPath)}${suffix}`;
+        link.properties.href = `${markdownUrlForDocPath(baseUrl, cleanPath)}${suffix}`;
       }
     };
-  })
-  .use(rehypeRemark)
-  .use(remarkGfm)
-  .use(remarkStringify, {
-    emphasis: "*",
-    strong: "*",
-  });
+  };
+}
+
+function buildHtmlToMarkdownPipeline(baseUrl: string) {
+  return unified()
+    .use(rehypeParse, { fragment: true })
+    .use(function improveExpressiveCodeHandling() {
+      return (tree) => {
+        const ecInstances = selectAll(
+          ".expressive-code",
+          tree as Parameters<typeof selectAll>[1],
+        );
+        for (const instance of ecInstances) {
+          // Remove the "Terminal Window" label from Expressive Code terminal frames.
+          const figcaption = select("figcaption", instance);
+          if (figcaption) {
+            const terminalWindowTextIndex = figcaption.children.findIndex(
+              (child) => matches("span.sr-only", child),
+            );
+            if (terminalWindowTextIndex > -1) {
+              figcaption.children.splice(terminalWindowTextIndex, 1);
+            }
+          }
+          const pre = select("pre", instance);
+          const code = select("code", instance);
+          // Use Expressive Code's `data-language=*` attribute to set a `language-*` class name.
+          // This is what `hast-util-to-mdast` checks for code language metadata.
+          if (pre?.properties.dataLanguage && code) {
+            if (!Array.isArray(code.properties.className))
+              code.properties.className = [];
+
+            const diffLines =
+              pre.properties.dataLanguage === "diff"
+                ? []
+                : code.children.filter((child) =>
+                    matches("div.ec-line.ins, div.ec-line.del", child),
+                  );
+            if (diffLines.length === 0) {
+              code.properties.className.push(
+                `language-${pre.properties.dataLanguage}`,
+              );
+            } else {
+              code.properties.className.push("language-diff");
+              for (const line of diffLines) {
+                if (line.type !== "element") continue;
+                const classes = line.properties?.className;
+                if (typeof classes !== "string" && !Array.isArray(classes))
+                  continue;
+                const marker = classes.includes("ins") ? "+" : "-";
+                const span = select("span:not(.indent)", line);
+                const firstChild = span?.children[0];
+                if (firstChild?.type === "text") {
+                  firstChild.value = `${marker}${firstChild.value}`;
+                }
+              }
+            }
+          }
+        }
+      };
+    })
+    .use(function improveTabsHandling() {
+      return (tree) => {
+        const tabInstances = selectAll(
+          "starlight-tabs",
+          tree as Parameters<typeof selectAll>[1],
+        );
+        for (const instance of tabInstances) {
+          const tabs = selectAll('[role="tab"]', instance);
+          const panels = selectAll('[role="tabpanel"]', instance);
+          // Convert parent `<starlight-tabs>` element to empty unordered list.
+          instance.tagName = "ul";
+          instance.properties = {};
+          instance.children = [];
+          // Iterate over tabs and panels to build a list with tab label as initial list text.
+          for (let i = 0; i < Math.min(tabs.length, panels.length); i++) {
+            const tab = tabs[i];
+            const panel = panels[i];
+            if (!tab || !panel) continue;
+            // Filter out extra whitespace and icons from tab contents.
+            const tabLabel = tab.children
+              .filter((child) => child.type === "text" && child.value.trim())
+              .map((child) => child.type === "text" && child.value.trim())
+              .join("");
+            // Add list entry for this tab and panel.
+            instance.children.push({
+              type: "element",
+              tagName: "li",
+              properties: {},
+              children: [
+                {
+                  type: "element",
+                  tagName: "p",
+                  children: [{ type: "text", value: tabLabel }],
+                  properties: {},
+                },
+                panel,
+              ],
+            });
+          }
+        }
+      };
+    })
+    .use(function improveFileTreeHandling() {
+      return (tree) => {
+        const trees = selectAll(
+          "starlight-file-tree",
+          tree as Parameters<typeof selectAll>[1],
+        );
+        for (const fileTree of trees) {
+          // Remove "Directory" screen reader labels from <FileTree> entries.
+          remove(fileTree, (_node) => {
+            const node = _node as Parameters<typeof matches>[1];
+            return matches(".sr-only", node);
+          });
+        }
+      };
+    })
+    .use(function removeHeadingAnchorLinks() {
+      return (tree) => {
+        // Remove Starlight's heading anchor links (e.g. "Section titled …").
+        // These are sibling <a> elements next to headings inside .sl-heading-wrapper divs.
+        remove(tree, (_node) => {
+          const node = _node as Parameters<typeof matches>[1];
+          return matches("a.sl-anchor-link", node);
+        });
+      };
+    })
+    .use(function removeInlineSemanticIcons() {
+      return (tree) => {
+        // Remove decorative semantic-reference icons such as the `fn` badge shown
+        // before links rendered by components like <Fn> and <Op>. In the markdown
+        // bundle, these should serialize as plain links only.
+        // The icons live inside `.semantic-link` anchors as `.inline-icon` children.
+        visit(tree, "element", (node: any) => {
+          if (!matches("a.semantic-link", node)) return;
+          node.children = node.children.filter(
+            (child: any) => !matches(".inline-icon", child),
+          );
+        });
+      };
+    })
+    .use(absolutizeInternalLinks(baseUrl))
+    .use(rehypeRemark)
+    .use(remarkGfm)
+    .use(remarkStringify, {
+      emphasis: "*",
+      strong: "*",
+    });
+}
+
+const pipelineCache = new Map<
+  string,
+  ReturnType<typeof buildHtmlToMarkdownPipeline>
+>();
+
+function getPipeline(baseUrl: string) {
+  let pipeline = pipelineCache.get(baseUrl);
+  if (!pipeline) {
+    pipeline = buildHtmlToMarkdownPipeline(baseUrl);
+    pipelineCache.set(baseUrl, pipeline);
+  }
+  return pipeline;
+}
+
+function resolveBaseUrl(context: APIContext): string {
+  const site = new URL(
+    ensureTrailingSlash(starlightLlmsTxtContext.base),
+    context.site,
+  );
+  return site.href.replace(/\/$/, "");
+}
 
 /** Render a content collection entry to HTML and back to Markdown to support rendering and simplifying MDX components */
 export async function entryToSimpleMarkdown(
@@ -215,6 +251,7 @@ export async function entryToSimpleMarkdown(
 ) {
   const { Content } = await render(entry);
   const html = await astroContainer.renderToString(Content, context);
-  const file = await htmlToMarkdownPipeline.process(html);
+  const baseUrl = resolveBaseUrl(context);
+  const file = await getPipeline(baseUrl).process(html);
   return String(file).trim();
 }