Repository navigation
docs(site): add a documentation home page at /docs - #402
Merged
Merged
Conversation
/docs returned 404 after the docs moved under it. Most developer-tool sites serve a documentation home at that address, so it now lists the quickstart path and the four sections, with links for agents. It has a Markdown export and appears in both LLM indexes, and Starlight card titles survive the Markdown conversion so each link keeps its section. The site header and the product's Docs link point at /docs, an address that stays stable when pages under it move.
Under build.format "file" Starlight wrote the file name into the site title, sidebar and previous/next links, so every click went through a redirect and showed .html in the address bar. "preserve" writes the same <path>.html files, which Cloudflare Pages serves at the extensionless path, and Starlight emits extensionless links for it. The canonical still comes from the file path, so the route middleware keeps correcting it, and check-docs-urls now fails the build on any link to a .html page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
fanout.run/docsreturned 404 after #399 moved the documentation under it. 17 of 22 surveyed developer-tool sites serve a documentation home at their docs root, so/docsnow has one: a one-line description, the quickstart path, cards for Get started, Guides, Reference and Concepts, and links for agents./docshas a Markdown export (/docs.md) and appears inllms.txtandllms-full.txt. Starlight card titles survive the Markdown conversion so each link keeps its section.ui/links.ts) point at/docs. The Connect telemetry and MCP links stay deep.internal/ui/distis rebuilt.build.format: "preserve"instead of"file". Pages are still written as<path>.htmland served extensionless by Cloudflare Pages, but Starlight's site title, sidebar and previous/next links no longer carry.html, so a click no longer goes through a redirect. The route middleware still corrects the canonical, andcheck-docs-urlsfails the build on any link to a.htmlpage.Verification
just checkjust test-racewhen auth, API, ingest, query, MCP, or agent paths changed (not applicable)just docs-generate-check)Also:
just site-build(33 docs pages verified, 0 links to.htmlpages, canonicals extensionless),just ui-test,bun test scripts/site-markdown.test.ts, and/docschecked in a local preview.