Skip to content

feat(docs): split v3 llms.txt into spec-compliant index and full dump#2284

Open
asblanco wants to merge 1 commit into
mainfrom
asblanco/stacks-864-v3-llms-split
Open

feat(docs): split v3 llms.txt into spec-compliant index and full dump#2284
asblanco wants to merge 1 commit into
mainfrom
asblanco/stacks-864-v3-llms-split

Conversation

@asblanco
Copy link
Copy Markdown
Contributor

@asblanco asblanco commented May 21, 2026

Summary

Mirrors the v2 split (#2283) for the v3 docs. The previous /llms.txt route produced a content-dump shape that doesn't match llmstxt.org (which wants an H1 + blockquote summary + H2 sections + markdown link lists).

This PR:

  • /llms.txt — spec-compliant index. One # Stacks H1, blockquote summary, 9 H2 sections (Brand, Copywriting, Develop, Accessibility, Foundation, Base, Forms, Components, Resources), and - [Title](url): description per page. HTML stripped from descriptions with the loop-until-stable pattern (CodeQL js/incomplete-multi-character-sanitization). ~15 KB / 89 entries.
  • /llms-full.txt — full content dump. Same content the previous /llms.txt produced, just at the new filename, plus the empty-collection bug fix.

Note

Implementation notes

  • The new /llms.txt reads markdown frontmatter via Vite's ?raw query rather than loading the compiled Svelte page module. This keeps the index independent of every page component's imports — a missing icon export in a leaf component can't break the index.
  • Pages not in structure.yaml (e.g. the standalone changelog.md) are skipped from the index by design — the YAML is the site's nav source of truth and decides what's a "page" worth indexing.

Warning

Coordination
Once this deploys, stacks-mcp-server PR #10 flips the Stacks v3 source URL in documentation-fetcher.ts from /llms.txt to /llms-full.txt. That PR is the v3 counterpart to stacks-mcp-server PR #9, which does the same for v2.

Test plan

  • Local dev server: curl http://localhost:5173/llms.txt returns 200 with spec shape (1 H1, 1 blockquote, 9 H2 sections, 89 link-list entries). Folder-index pages get trailing-slash URLs; plain .md pages don't.
  • After deploy: curl https://stackoverflow.design/llms.txt returns the spec-shape index.
  • After deploy: curl https://stackoverflow.design/llms-full.txt returns the full content dump.
  • Confirm the follow-up MCP change can then index v3 successfully.

JIRA: STACKS-864

@asblanco asblanco requested a review from a team as a code owner May 21, 2026 09:52
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented May 21, 2026

⚠️ No Changeset found

Latest commit: 5398e73

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@netlify
Copy link
Copy Markdown

netlify Bot commented May 21, 2026

Deploy Preview for stacks ready!

Name Link
🔨 Latest commit 5398e73
🔍 Latest deploy log https://app.netlify.com/projects/stacks/deploys/6a0ed5e87392610008de987b
😎 Deploy Preview https://deploy-preview-2284--stacks.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@asblanco asblanco enabled auto-merge (squash) May 21, 2026 09:55
@asblanco asblanco self-assigned this May 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant