Skip to content

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.

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.

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.

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.

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”.

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.

Used by nav, hero.primary/secondary and cta.primary/secondary.

Field Type Required Description
label string yes
href string yes

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

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.

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
astro-project-site

A whole site for your open-source project, from one Astro integration.

© 2026 astro-project-site · v0.1.0-beta.6 · MIT licence. This site is built with itself.