projectSite(options) takes one object. It is validated before Astro starts: an unknown key or a wrong type
fails with the field’s path (landing.hero.primary.href: …, unknown option "navv"). Paths (customCss,
components.*, ogImageFor, versionFrom, externalDocs[].dir, mirrors[].from) are relative to the project
root (the folder of astro.config.mjs) and may point outside it; local files must exist.
Types and descriptions come from src/index.d.ts, defaults and required fields from the zod schema in
src/options.mjs; the generator fails if the two disagree on which options exist.
projectSite()
Section titled “projectSite()”| Option | Type | Default | Description |
|---|---|---|---|
name |
string |
required | Project name, shown in the header and titles. |
tagline |
string |
required | One line under the name on the landing page and in meta descriptions. |
url |
string |
required | Production URL. Also Astro’s site unless that is set. |
repo |
string |
required | Source repository, for “edit this page” and the header link. GitHub URL layout is assumed for file links. |
repoBranch |
string |
"main" |
Branch that edit links and links to repo files point at. Default main. |
versionFrom |
string |
A package.json (relative to the project root) whose version the header shows. |
|
nav |
LinkAction[] |
Top navigation, shared by every page. Default: Docs, and Gallery unless gallery: false. |
|
externalDocs |
ExternalDocs[] |
[] |
Markdown folders outside the site, mounted under /docs/<route>/. |
docsOrder |
string[] |
[] |
The order of the top-level docs sections, in the sidebar and in the docs cards (the /docs/ page and the landing page): mount routes (externalDocs[].route, e.g. reference) and folders of src/content/docs/docs/ (e.g. guide). Listed sections come first, in this order; the rest follow in the default order (mounts as configured, then your own folders by name). Pages directly in src/content/docs/docs/ always come first. An unknown name fails the build. Default: none. |
mirrors |
Mirror[] |
[] |
Static HTML/JS folders copied into the build byte for byte (and served from disk in dev). |
install |
string |
Install command shown on the landing page. | |
favicon |
string |
"/favicon.svg" |
Favicon path under public/. Default /favicon.svg. |
head |
HeadTag[] |
[] |
Tags added to the <head> of every page: landing, gallery, your BaseLayout pages and docs. |
ogImage |
string |
Default social image: a path under public/ (1200×630) or an absolute URL. | |
ogImageFor |
string |
Module (relative to the project root) whose default export is an OgImageHook, for per-page images. |
|
theme |
object |
{} |
Accent colour overrides. For more, override the --site-* tokens in customCss. |
theme.accent |
string |
||
theme.accentDark |
string |
||
landing |
false | LandingContent |
{} |
Content of the built-in landing page at /, or false for none (or add your own src/pages/index.astro). |
gallery |
false | { route?: string; title?: string; description?: string } |
{} |
The built-in gallery page, or false for none. route is its URL path (default gallery: /gallery/); title and description default to the gallery and galleryDescription labels. |
blog |
boolean | BlogOptions |
false |
Posts from src/content/blog/ at /blog/ (list, posts, tags, RSS), or true for the defaults. Off unless set. |
footer |
object |
{} |
Footer text. note: extra text, e.g. a licence line. copyright: the copyright line, with {year} (the build year) and {name} filled in; default the copyright label (“© {year} {name}”); false leaves it out. |
footer.note |
string |
||
footer.copyright |
string | false |
||
labels |
Partial<Labels> |
{} |
The words the template puts on pages (buttons, screen-reader names, empty states, alert titles), by name. They follow the site’s language (Starlight’s root or default locale): built in for English, French, German and Spanish, English for anything else. Set any of them here, in any language. |
llms |
boolean |
true |
Serve /llms.txt and /llms-full.txt. Default true. |
linksValidator |
false | Record<string, unknown> |
Options for starlight-links-validator, which fails the build on a broken link in a docs page, or false to turn it off. Links to the landing page, the gallery, llms.txt and mirrored folders are always accepted; exclude adds to that list. |
|
customCss |
string[] |
[] |
Stylesheets (relative to the project root) loaded on every page after theme.css: override tokens here. |
components |
ComponentOverrides |
{} |
Replace built-in components. |
starlight |
Record<string, unknown> |
{} |
Extra Starlight options, passed through. List options are appended to the ones projectSite() sets: sidebar (after the generated sidebar), plugins, customCss (docs pages only), routeMiddleware, markdown.processedDirs. components entries override ours (e.g. your own Header replaces the shared one). |
markdown |
MarkdownOptions |
{} |
GitHub-flavoured markdown extras, on every page that renders markdown. Each switch defaults to true. |
When nav is not set it defaults to Docs (/docs/), plus Gallery (/gallery/) unless gallery: false.
url and repo lose any trailing slash.
ExternalDocs
Section titled “ExternalDocs”An entry of externalDocs. See Docs: mounting external markdown.
| Field | Type | Required | Description |
|---|---|---|---|
dir |
string |
Markdown folder, relative to the project root. May be outside it (../docs). Give this or git. |
|
git |
GitSource |
A folder of another repository instead of a local one: downloaded at build time (a shallow, sparse fetch with the git command), cached in Astro’s cache folder, then mounted like dir. Links to its files that are not mounted go to that repository at ref; “Edit page” goes to its default branch. |
|
route |
string |
yes | URL segment under /docs/: reference → /docs/reference/… |
label |
string |
yes | Sidebar group label. |
description |
string |
One sentence on what the section holds: its card on /docs/ and the landing page, and the meta description of its README page. Defaults to the README’s frontmatter description, then its first paragraph. |
|
order |
string[] |
File names (relative to dir, .md optional) listed first, in this order. README.md always leads. |
|
exclude |
string[] |
Globs relative to dir to leave out, e.g. ['plans/**']. |
|
include |
string[] |
Globs relative to dir; when given, only matching markdown files are mounted. Matched against the whole path (README.md is the top-level one only); a glob that matches a folder covers its contents. Lets a mount pick files from the repository root: { dir: '..', route: 'project', label: 'Project', include: ['README.md', 'CHANGELOG.md'] }. The site’s own folder, dot-folders and node_modules are never mounted. |
Mirror
Section titled “Mirror”An entry of mirrors. See Mirrors.
| Field | Type | Required | Description |
|---|---|---|---|
from |
string |
yes | Folder to serve as-is, relative to the project root. May be outside it (../). |
to |
string |
yes | URL prefix: apps → /apps/… Nested prefixes (pixel/src) work. |
include |
string[] |
Globs relative to from; when given, only matching paths are mirrored. |
|
exclude |
string[] |
Globs relative to from; matching paths are skipped. |
LandingContent
Section titled “LandingContent”The landing option. Every part is optional; a section without content is not rendered.
See Landing page.
| Field | Type | Required | Description |
|---|---|---|---|
hero |
object |
||
hero.title |
string |
Big heading; defaults to name. |
|
hero.lead |
string |
Paragraph under the heading; defaults to tagline. |
|
hero.primary |
LinkAction |
||
hero.secondary |
LinkAction |
||
hero.demo |
HeroDemo |
A live example under the hero copy (rendered with <Live>). |
|
features |
SectionContent<Feature> |
Feature cards. Default heading: the featuresTitle label (“Why it exists”). |
|
docs |
false | { title?: string; intro?: string } |
Cards for the top-level docs sections, shown when there are no features and the docs have at least two sections. Default heading: the documentation label. false hides them. |
|
steps |
SectionContent<Step> |
Numbered steps. Default heading: the stepsTitle label (“How it works”). |
|
gallery |
object |
The gallery strip: heading, intro and how many items (0 hides it; default 3). | |
gallery.title |
string |
||
gallery.intro |
string |
||
gallery.limit |
number |
||
cta |
object |
||
cta.title |
string |
yes | |
cta.body |
string |
||
cta.primary |
LinkAction |
||
cta.secondary |
LinkAction |
features and steps take either an array of items or { title, intro, items }. The default headings are
“Why it exists” (with the intro “The short version, for people deciding whether to read on.”) and
“How it works”.
Feature
Section titled “Feature”| Field | Type | Required | Description |
|---|---|---|---|
title |
string |
yes | |
body |
string |
yes | |
href |
string |
Makes the whole card a link. |
| Field | Type | Required | Description |
|---|---|---|---|
title |
string |
yes | |
body |
string |
yes | |
code |
string |
Code shown next to the step, highlighted at build time. | |
lang |
string |
Shiki language id, e.g. js, ts, sh. |
LinkAction
Section titled “LinkAction”Used by nav, hero.primary/secondary and cta.primary/secondary.
| Field | Type | Required | Description |
|---|---|---|---|
label |
string |
yes | |
href |
string |
yes |
HeroDemo
Section titled “HeroDemo”landing.hero.demo: a <Live> example under the hero copy.
| Field | Type | Required | Description |
|---|---|---|---|
code |
string |
yes | |
lang |
string |
||
title |
string |
||
caption |
string |
||
mode |
'inline' | 'iframe' |
||
preview |
'above' | 'below' | 'side' |
||
runner |
string |
||
editable |
boolean |
||
options |
Record<string, unknown> |
||
modules |
string[] |
||
base |
string |
||
height |
number | string |
ComponentOverrides
Section titled “ComponentOverrides”The components option. Values are paths relative to the project root, or package specifiers.
See Overriding components.
| Field | Type | Required | Description |
|---|---|---|---|
Header |
string |
The header bar contents on every page, docs included. Receives the search, theme and theme-menu slots. |
|
Footer |
string |
The footer on every page, docs included. Receives variant: 'page' | 'docs'. |
|
Hero |
string |
The landing page’s hero. Receives the Hero props (title, lead, primary, secondary, install) and a live slot. |
|
Landing |
string |
The whole landing page body (inside BaseLayout). | |
GalleryCard |
string |
One gallery card. Receives item: GalleryEntry and headingLevel. |
|
Gallery |
string |
The whole /gallery/ page body (inside BaseLayout). Receives items, title, description. |
|
BlogIndex |
string |
The post list body (inside BaseLayout): /blog/, /blog/2/, and each /blog/tags/<tag>/. Receives BlogIndexProps. |
|
BlogPost |
string |
One post page body (inside BaseLayout). Receives BlogPostProps; the rendered post is its default slot. |
|
BlogCard |
string |
One post in a list (blog index, tag pages, landing “Latest posts”). Receives post: BlogEntry, headingLevel. |
OgImageRequest
Section titled “OgImageRequest”What an ogImageFor module’s default export (OgImageHook) receives. It returns a root-relative or absolute
image URL, or undefined for none.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string |
yes | Path of the page, e.g. /gallery/ or /docs/reference/api/. |
title |
string |
yes | |
description |
string |
yes |