Configuration

Everything you change to make this site yours lives in src/docs.config.ts. You do not need to edit src/components/, src/styles/, or worker/ to rebrand the site, change its navigation, or turn features on and off. If you find yourself editing those files to change a string, treat that as a bug in this configuration file, not something to work around.

The configuration file has five exports.

site — identity

This export sets the name, title suffix, description, header and footer links, and the assistant menu. The description is the site-level meta description and the blockquote in llms.txt. Write one real sentence for it, not a slogan.

basePath decides where the documentation sits under its domain. Use '' for docs.example.com/page, or '/docs' for example.com/docs/page. This one setting moves every generated URL. The Worker strips the prefix back off before it looks anything up. basePath must stay in step with Astro’s base in astro.config.ts, so both settings read from the same constant. See DEPLOYMENT.md for the topologies, the Cloudflare route, and the three things a subpath cannot have.

One rule comes with basePath. An internal link written by hand in this file must carry the prefix itself (`${basePath}/getting-started`). Links built from a page id go through hrefFor, which applies the prefix for you. An authored string without the prefix is indistinguishable from a link to another site.

homePageId is the one subtle field. Leave it undefined for a docs-first site whose home page is its first page. Set it to a content id to serve that page at /, outside the navigation. That page stays published, indexed, and in the corpus, but it is not a sidebar item and takes no part in previous/next navigation. A page named here must not also appear in navigation. The build refuses that combination, because the page would be reachable at two URLs.

banner is a site-wide announcement fixed above the navbar. It takes content, a tone (info, warning, or critical), dismissible, and an optional color per colour mode. Leave it undefined for no strip. The site stores a dismissal against the exact text, so publishing new wording shows the banner again to everyone who dismissed the previous version. This same behaviour makes the strip unsuitable for anything a reader must not be able to hide.

Turning the banner on changes the shell’s geometry, and nothing in this file has to account for that. The height lives in --banner-h (src/styles/tokens.css). Every fixed bar, the document’s top padding on both desktop and mobile, and scroll-padding-top all derive from that one value.

seo — search and generative engines

This export sets the publisher identity for the JSON-LD graph, the locale, the AI crawler allowlist, and Cloudflare Content Signals.

Write agentInstructions with care. The build emits it as prose at the top of llms.txt and llms-full.txt, in the space the llmstxt.org format leaves between the summary and the links. Limit it to facts a model cannot infer from the pages: which document wins when two disagree, what the site does not cover, and what it must not guess at. Restating the product description adds no value, because site.description already sits directly above it.

The build deliberately does not prepend agentInstructions to every page’s Markdown. That would put the same paragraph in front of a reader who clicked “Copy page” for one answer. It would also make anything crawling the corpus re-read the paragraph once per page.

theme — brand

This export sets the font, accent, and radius. The build injects these as CSS custom properties, so changing the accent is one line. The neutral palette and component styling live in src/styles/.

accent.strong exists because accent.base usually cannot clear a 4.5:1 contrast ratio against the accent tints used behind badges and method pills. It can only clear that ratio against the page background. Check both contrasts when you change the accent.

Changing the page background

--bg in src/styles/tokens.css is the one colour a site most often wants to move, for example to a light grey canvas that matches a marketing site. Change only this value. The raised surfaces follow it automatically.

--surface-2 (hover) and --surface-active (the current item) are not fixed colours. Each is --bg mixed a measured distance toward --text in OKLab. This holds the same perceptual separation from whatever background you set, in both colour modes. The percentages differ by mode because perceived contrast differs by mode: dark mode needs roughly twice the lightness step to read the same as light mode.

These values used to be absolute colours, which worked only while --bg stayed white. One site set --bg: #f5f5f5 and got a --surface-2 of #f5f5f5 too. The selected sidebar item then rendered in exactly the page colour and disappeared. Nothing was misconfigured. The tokens simply did not know the background had moved. If you find yourself hand-picking a second colour after changing --bg, that is the same bug returning.

navigation — structure

This export lists tabs, groups, and page ids in sidebar order. Labels, descriptions, icons, and badges come from each page’s own frontmatter. This export never restates them.

navigationLayout.mode switches between category-tabs (large categories in a bar under the navbar) and unified-sidebar (everything in one left rail). Changing this mode never changes routes, content, or navigation data.

The build validates this export against the content collection. A page id with no matching file fails the build. A published page that belongs to no group also fails the build. A page id that names a draft is skipped silently, and it takes any group or tab it would have emptied with it. This last case is what lets you leave work-in-progress listed here while it stays unpublished. See Drafts.

agents — the MCP server, HTTP API and WebMCP

export const agents = {
  enabled: true,            // master switch for all three surfaces
  http: true,               // also serve /api/docs/*
  retrieval: 'lexical',     // or 'ai-search'
  aiSearchInstance: '…',
  defaultLimit: 8,
  maxLimit: 25,
  feedback: { webhook: undefined, fields: [ … ], context: [ … ] },
  webmcpBridge: 'off',      // 'on' where there is no Cloudflare zone
  rateLimit: { search: 30, read: 90, write: 2 },
};

Setting enabled: false registers no routes, provisions nothing, and skips the index upload. A site that wants plain documentation carries none of that cost. Full detail in AGENTS.md.

Also configurable

• src/openapi.config.ts: the OpenAPI document the endpoint pages render from. Leave the empty stub, and the build emits no /openapi.json and advertises nothing. A site with no API should not publish a spec with no paths, because an agent may read that as evidence that the API has no endpoints.
• src/icon-aliases.ts: short names for icons.
• public/_headers: caching and security headers.
• wrangler.jsonc: the Worker, its asset routing, and the rate limiting bindings.

The values every site must set

A fresh clone runs as is. npm run dev, npm run build, and npm test all pass with nothing configured, because every service integration defaults to off and search falls back to the built lexical index. This is intentional. The alternative is a template that fails on first contact until you set up an account somewhere.

The cost of that choice is that a fresh clone carries this site’s values. Those values are wrong for your site, often in ways that are easy to miss. The list below orders them by how soon each one will cause a problem.

Set the origin before anything else. Export SITE_URL in the deploy environment rather than editing the fallback. This way, a preview build and a production build cannot disagree.

Secrets

There is one file, .env.example. Copy it to .env and fill in what you need. .env is gitignored.

Only two values are real secrets. Both are used only by scripts/index-sync.mjs, and neither reaches the Worker. The Worker queries the index through its AI_SEARCH binding instead:

• CLOUDFLARE_ACCOUNT_ID
• AI_SEARCH_TOKEN: not the token wrangler holds. Create a separate token under AI → AI Search → Tokens with AI Search:Edit and AI Search:Run.

agents.feedback.webhook is notably not a secret. The build reads it at build time and compiles it into the Worker bundle, so a URL that carries a token would be served to anyone who asks for it. Use a receiver that authenticates some other way.

Switching semantic retrieval on takes three edits, and all three must agree. This is the usual way it goes wrong. Uncomment the ai_search binding in wrangler.jsonc, set agents.retrieval to 'ai-search', and set agents.aiSearchInstance to the same instance name used in the binding. Then run npm run index:sync.

The instance name appears twice on purpose, and the two copies must agree. The Worker queries through the binding, while scripts/index-sync.mjs reads the name out of the config to build its REST URL. A mismatch causes no visible error. The Worker keeps answering, either from the wrong index or from none.

Once semantic retrieval is on, npm run deploy chains index:sync between the build and wrangler deploy. This makes a deploy from a shell without the two credentials fail before it ships, instead of shipping a Worker that queries an index one version behind. AGENTS.md covers creating the instance, the settings that are not obvious from the dashboard, and how the index is reconciled.