Configuration Reference

This page documents every configuration option available in the documentation site.

astro.config.mjs

The main configuration file uses Astro’s defineConfig helper with the Starlight integration:

import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  site: "https://docs.example.com",       // Canonical URL
  integrations: [
    starlight({
      title: "Docs",                       // Site title
      sidebar: [/* ... */],                // Navigation structure
      // ...additional options
    }),
  ],
});

Top-level Astro options

Option	Type	Default	Description
`site`	`string`	—	Canonical URL, used for sitemaps and `<link rel="canonical">`
`base`	`string`	`"/"`	Base path if the site is not served from the root
`output`	`"static" \| "server"`	`"static"`	Output mode; keep `static` for documentation
`trailingSlash`	`"always" \| "never" \| "ignore"`	`"ignore"`	Whether URLs end with a slash

Starlight options

Option	Type	Description
`title`	`string`	Site title shown in header and browser tab
`logo`	`object`	Logo image with `light` and `dark` variants
`sidebar`	`SidebarItem[]`	Navigation structure (see Customization)
`social`	`object`	Social media links shown in the header
`defaultLocale`	`string`	Default language code (e.g., `"en"`)
`locales`	`object`	i18n locale definitions
`customCss`	`string[]`	Paths to custom CSS files for theming
`head`	`HeadConfig[]`	Custom elements injected into `<head>`
`editLink`	`object`	”Edit this page” link configuration
`tableOfContents`	`object \| false`	On-page table of contents settings
`lastUpdated`	`boolean`	Show “Last updated” date on pages
`pagination`	`boolean`	Show previous/next page links

Environment variables

Environment variables are loaded from a .env file (or your hosting provider’s settings). Variables prefixed with PUBLIC_ are available in the browser.

All variables

Variable	Prefix	Required	Description
`SITE_URL`	—	No	Canonical URL; used at build time for sitemaps
`PUBLIC_SUPABASE_URL`	`PUBLIC_`	No	Supabase project URL (e.g., `https://abc.supabase.co`)
`PUBLIC_SUPABASE_ANON_KEY`	`PUBLIC_`	No	Supabase anonymous API key for client-side requests
`PUBLIC_GA_MEASUREMENT_ID`	`PUBLIC_`	No	Google Analytics 4 measurement ID

Supabase setup

To enable interactive features (feedback widget and search):

Create a Supabase project
Run the migration: npx supabase db push (or apply supabase/migrations/20240101000000_initial_schema.sql manually)
Optionally load seed data: npx supabase db seed
Copy the project URL and anon key from Settings > API into your .env

Without Supabase credentials, the site works normally — feedback and search components are hidden or fall back to static behavior.

TypeScript configuration

TypeScript is configured through tsconfig.json (generated by Astro) and used by:

npm run check — Astro type checking for .astro files
npm run typecheck — Standard tsc --noEmit for .ts files

Strict mode is enabled by default. Path aliases use @/ to reference src/.

Content collection schema

The docs collection is defined in src/content.config.ts using the Starlight schema:

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};

The schema validates frontmatter automatically. Required fields: title. Optional fields include description, sidebar, tableOfContents, draft, hero, and banner.

Build output

Command	Output	Description
`npm run build`	`dist/`	Production-ready static files
`npm run dev`	—	Development server on port 4321
`npm run preview`	—	Preview of the production build