All configuration is the object passed to projectSite() in astro.config.mjs. This page covers the options
that describe the project; the others have their own guides. Full table: Options.
Identity
Section titled “Identity”projectSite({ name: 'My Lib', // header, page titles ("Usage | My Lib"), Starlight's title tagline: 'Parses things, quickly.', // landing lead, default meta description url: 'https://my-lib.dev', // canonical URLs, sitemap, og:image; Astro's `site` unless you set it repo: 'https://github.com/me/my-lib', // header link, edit links, links to source files repoBranch: 'main', // default 'main' versionFrom: '../package.json', // header shows "v1.4.0", linked to <repo>/releases install: 'npm i my-lib', // landing page install command with a copy button}),urlandrepomust be full URLs; a trailing slash is dropped.repoon github.com, gitlab.com or codeberg.org gets that site’s icon and name in the header and in Starlight’s mobile menu; anything else is labelled “Source code”. Edit and source links always use GitHub’s URL layout.versionFromis read when the dev server starts (and watched). A file without aversionlogs a warning and shows no version.
Navigation
Section titled “Navigation”nav is the top navigation on every page, docs included (on small docs screens it moves into Starlight’s
menu, so there is one menu button). A link is marked current when the page path starts with its href.
nav: [ { label: 'Docs', href: '/docs/' }, { label: 'Playground', href: '/apps/hello/' }, { label: 'Changelog', href: 'https://github.com/me/my-lib/releases' },],Without nav you get Docs, plus Gallery unless gallery: false. The footer repeats nav and adds a “Source”
link.
Social images and favicon
Section titled “Social images and favicon”favicon: '/favicon.svg', // under public/; the defaultogImage: '/og.png', // 1200×630 under public/, or a full URLogImageFor: './src/og.mjs', // per-page images, docs pages included/** @type {import('astro-project-site').OgImageHook} */export default function ogImageFor({ path, title, description }) { if (path.startsWith('/docs/reference/')) return '/og/reference.png'; return '/og.png'; // or undefined for no image}Pages with an image get og:image and a summary_large_image Twitter card. Image paths become absolute
against url.
Footer, llms.txt, link checking
Section titled “Footer, llms.txt, link checking”footer: { note: 'Released under the MIT licence.' }, // after "© 2026 My Lib · v1.4.0"llms: true, // /llms.txt and /llms-full.txt (default)linksValidator: { exclude: ['/api/**'] }, // or false to turn link checking offlinksValidator takes starlight-links-validator’s options.
The landing page, /gallery/, /llms*.txt and every mirror prefix are always accepted as link targets;
your exclude is added to that list.
Accent colour
Section titled “Accent colour”theme: { accent: '#c2541b', accentDark: '#ffb347' }, // light theme, dark themeaccentDark falls back to accent. For anything beyond the accent (backgrounds, fonts, radius), override the
tokens in CSS: Theming.
Keeping the config readable
Section titled “Keeping the config readable”The config is plain JavaScript; split it however you like. This site keeps its docs options in a second file and spreads them in:
/** @type {Partial<import('astro-project-site').ProjectSiteOptions>} */export default { externalDocs: [{ dir: '../docs', route: 'reference', label: 'Reference' }],};import docs from './docs.config.mjs';// …projectSite({ ...docs, name: 'My Lib', /* … */ }),Using the options in your own pages
Section titled “Using the options in your own pages”---import { BaseLayout, Section } from 'astro-project-site/components';import config from 'astro-project-site/config';---<BaseLayout title="About" description={`Who makes ${config.name}`}> <Section title={`About ${config.name}`} intro={config.tagline}> <p>Version {config.version}. Source: <a href={config.repo}>{config.repo}</a></p> </Section></BaseLayout>BaseLayout gives a page the shared header, footer, theme switch and meta tags. config is the validated
options (see Exports).