From 0e35d9f052f8e104bb31b49a7c9779778e8c90e6 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk Date: Fri, 8 May 2026 08:07:45 +0000 Subject: [PATCH 1/3] AFDocs fixes: improve llms-txt-coverage with complete customSets - Add root pages (index, quickstart) to the Getting Started custom set - Simplify Support custom set to use support-and-community/** glob instead of manually listing individual pages, which missed warp-preview-and-alpha-program - Fix indentation inconsistency in customSets config Co-Authored-By: Oz --- astro.config.mjs | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index c809821..720a6fd 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -150,14 +150,15 @@ export default defineConfig({ { label: 'Agent Platform', description: 'Warp\'s Agent Platform: capabilities, local agents, CLI agents, cloud agents.', paths: ['agent-platform/**'] }, { label: 'Code', description: 'Code editor, code review, and Git worktrees.', paths: ['code/**'] }, { label: 'Enterprise', description: 'Enterprise features, SSO, team management, and security.', paths: ['enterprise/**'] }, - { label: 'Getting Started', description: 'Installation, quickstart, and migration guides.', paths: ['getting-started/**'] }, + { label: 'Getting Started', description: 'Installation, quickstart, and migration guides.', paths: ['index', 'quickstart', 'getting-started/**'] }, { label: 'Knowledge and Collaboration', description: 'Warp Drive, teams, and the Admin Panel.', paths: ['knowledge-and-collaboration/**'] }, { label: 'Reference', description: 'CLI and API reference.', paths: ['reference/**'] }, - // Includes all support-and-community/ pages except open-source-licenses.mdx - // (excluded globally above — ~25k lines causes a stack overflow in hast-util-to-text). - { label: 'Support', description: 'Troubleshooting, billing, and privacy.', paths: ['support-and-community/index', 'support-and-community/plans-and-billing/**', 'support-and-community/privacy-and-security/**', 'support-and-community/troubleshooting-and-support/**', 'support-and-community/community/contributing', 'support-and-community/community/open-source-partnership', 'support-and-community/community/refer-a-friend'] }, - { label: 'Guides', description: 'Task-oriented walkthroughs and tutorials.', paths: ['guides/**'] }, - { label: 'Changelog', description: 'Warp release notes by year.', paths: ['changelog/**'] }, + // All support-and-community/ pages. open-source-licenses.mdx is excluded + // from llms-small.txt globally above (stack overflow in hast-util-to-text) + // but still included here for llms-full.txt and the Support set. + { label: 'Support', description: 'Troubleshooting, billing, and privacy.', paths: ['support-and-community/**'] }, + { label: 'Guides', description: 'Task-oriented walkthroughs and tutorials.', paths: ['guides/**'] }, + { label: 'Changelog', description: 'Warp release notes by year.', paths: ['changelog/**'] }, ], }), ], From a2488294934cb33de1edaaf243609e4a8457ef2e Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 8 May 2026 09:26:14 -1000 Subject: [PATCH 2/3] Add /api to markdown-url-support allowlist in known-exceptions /api is a custom Astro page, not a Starlight doc page, so it won't have a .md variant. This is expected and intentional. Co-Authored-By: Oz --- .agents/skills/afdocs-audit/references/known-exceptions.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.agents/skills/afdocs-audit/references/known-exceptions.md b/.agents/skills/afdocs-audit/references/known-exceptions.md index 86c0085..87ca601 100644 --- a/.agents/skills/afdocs-audit/references/known-exceptions.md +++ b/.agents/skills/afdocs-audit/references/known-exceptions.md @@ -46,6 +46,12 @@ This file lists checks from the afdocs-audit skill that may flag as warnings or **Reason**: Only evaluated when tab panels contain section headers. Most sampled pages with tabs don't have headers inside the tab panels, so the check is skipped. **Action**: None needed. +## markdown-url-support + +**Expected status**: fail (for `/api`) +**Reason**: `/api` is a custom Astro page (`src/pages/api.astro`), not a Starlight content page. The docs-markdown integration only generates `.md` variants for Starlight doc pages under `src/content/docs/`, so `/api.md` does not exist. +**Action**: No fix needed. This page is intentionally outside the Starlight content pipeline. + ## auth-alternative-access **Expected status**: skip From b92f328b7eda063074cf908e0667b82bf50402cf Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 8 May 2026 10:56:42 -1000 Subject: [PATCH 3/3] Extend starlight-llms-txt patch to exclude pages from custom sets The upstream plugin only applied the `exclude` option to llms-small.txt. Our existing patch already extended it to llms-full.txt; this adds the same exclude pass to llms-custom.txt.ts so custom sets (e.g. the Support set) also skip pages that cause a stack overflow in hast-util-to-text. Fixes the build failure caused by `support-and-community/**` including the ~25k-line open-source-licenses page in the Support custom set. Co-Authored-By: Oz --- astro.config.mjs | 13 +++++++------ patches/starlight-llms-txt+0.8.1.patch | 12 ++++++++++++ 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index 720a6fd..9aebdb8 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -139,10 +139,11 @@ export default defineConfig({ // widely consumed by AI agents. starlightLlmsTxt({ projectName: 'Warp', - // Excludes pages from llms-small.txt that cause a stack overflow - // in hast-util-to-text due to their size. Note: the `exclude` - // option only applies to llms-small.txt, not llms-full.txt. - exclude: ['support-and-community/community/open-source-licenses'], + // Excludes pages that cause a stack overflow in hast-util-to-text + // due to their size. The upstream plugin only applies `exclude` to + // llms-small.txt; our patch (patches/starlight-llms-txt+0.8.1.patch) + // extends it to llms-full.txt and custom sets as well. + exclude: ['support-and-community/community/open-source-licenses'], description: 'Documentation for Warp, the agentic development environment, and Oz, Warp\'s programmable agent for running and coordinating agents at scale.', customSets: [ @@ -154,8 +155,8 @@ export default defineConfig({ { label: 'Knowledge and Collaboration', description: 'Warp Drive, teams, and the Admin Panel.', paths: ['knowledge-and-collaboration/**'] }, { label: 'Reference', description: 'CLI and API reference.', paths: ['reference/**'] }, // All support-and-community/ pages. open-source-licenses.mdx is excluded - // from llms-small.txt globally above (stack overflow in hast-util-to-text) - // but still included here for llms-full.txt and the Support set. + // globally above (stack overflow in hast-util-to-text); the patch ensures + // it's excluded from this custom set as well. { label: 'Support', description: 'Troubleshooting, billing, and privacy.', paths: ['support-and-community/**'] }, { label: 'Guides', description: 'Task-oriented walkthroughs and tutorials.', paths: ['guides/**'] }, { label: 'Changelog', description: 'Warp release notes by year.', paths: ['changelog/**'] }, diff --git a/patches/starlight-llms-txt+0.8.1.patch b/patches/starlight-llms-txt+0.8.1.patch index 85cca12..e3dc751 100644 --- a/patches/starlight-llms-txt+0.8.1.patch +++ b/patches/starlight-llms-txt+0.8.1.patch @@ -1,3 +1,15 @@ +diff --git a/node_modules/starlight-llms-txt/llms-custom.txt.ts b/node_modules/starlight-llms-txt/llms-custom.txt.ts +index f96dbbd..7f19ab5 100644 +--- a/node_modules/starlight-llms-txt/llms-custom.txt.ts ++++ b/node_modules/starlight-llms-txt/llms-custom.txt.ts +@@ -30,6 +30,7 @@ export const GET: APIRoute = async (context) => { + minify: true, + description, + include: context.props.paths, ++ exclude: starlightLllmsTxtContext.exclude, + }); + return new Response(body); + }; diff --git a/node_modules/starlight-llms-txt/llms-full.txt.ts b/node_modules/starlight-llms-txt/llms-full.txt.ts index 03f408b..9907aed 100644 --- a/node_modules/starlight-llms-txt/llms-full.txt.ts