Starlight Site Setup

The internal documentation site is an Astro Starlight project. Its configuration and brand assets are maintained in the repository rather than copied into individual pages.

Source locations

• astro.config.mjs owns the site URL, navigation, logo, favicon, and custom CSS registration.
• src/styles/custom.css owns the Starlight theme overrides.
• src/assets/n1-logo.png is the configured navigation logo.
• public/favicon.png is the configured browser icon.
• src/content/docs/ is the only canonical source for employee-facing documentation.

Add or reorganize navigation in astro.config.mjs. Put document-owned assets in src/assets/, and use public/ only for retained static artifacts that need stable URLs. Do not create hand-authored copies under public/raw/; the build emits raw Markdown and raw-manifest.json from the canonical source.

Verification

Run the repository documentation checks before opening a pull request:

npm run docs:lint
npm run docs:links
npm run docs:assets
npm run docs:raw

Use npm run ci for the complete repository gate. When changing the legacy migration ledger, also run npm run docs:audit.

Last verified: 2026-08-24 against astro.config.mjs, the authoring contract, and the current package scripts.