# astro-project-site > A whole site for your open-source project, from one Astro integration. --- # Overview URL: https://astro-project-site.pascaripavel.workers.dev/docs/ **astro-project-site** is one Astro integration that gives an open-source library or framework its website: - a **landing page** written as config (hero, features, steps, gallery strip, call to action) or as your own page built from the same components; - **Starlight docs** that mount your repo's existing `docs/` folder as it is: titles from the first heading, `.md` links rewritten, "edit this page" links into the right folder, a generated sidebar, link checking, search, `llms.txt`; - **live examples** (``): the code on the page is the code that runs, inline or in an iframe, editable, with your own runner for JSON specs or DSLs; - a **gallery** of demos with posters and filters; - **mirrors**: static HTML/JS folders (a playground, your library's `src/`) served byte for byte next to the docs; - **generated docs blocks** (`docs:gen` / `docs:check`) so API tables cannot drift from the code; - **Cloudflare Workers deploys** with a preview URL per pull request, `next` from `main` and production from tags. This site is built with it. The page you are reading is a local MDX page, and the reference tables are generated from the package source. The [starter](https://project-site-starter.pascaripavel.workers.dev/), deployed as `init` creates it, shows a mounted folder: its [Reference](https://project-site-starter.pascaripavel.workers.dev/docs/reference/) is plain markdown mounted with `externalDocs`. ## What it is not - **Not a fork of Starlight.** It configures Starlight for you and passes anything else through ([`starlight` option](https://astro-project-site.pascaripavel.workers.dev/docs/guides/overriding-components/#starlight-passthrough)). Starlight plugins, components and frontmatter work as documented upstream. - **Not a theme you copy and edit.** Upgrades come from npm. You change the site with options, CSS tokens and component overrides. - **Not multilingual yet.** One locale; see [i18n](https://astro-project-site.pascaripavel.workers.dev/docs/recipes/i18n/). - **Not a server.** The output is static files. The deploy tooling targets Cloudflare Workers static assets, but `dist/` works on any static host. - **GitHub-shaped.** Edit links and links to source files use GitHub's URL layout (`/edit/`, `/blob/`, `/tree/`). Requirements: Node 22.23.4+ (or 24), Astro 7.4.7+, Starlight 0.43+. ## Where to go ## For agents Everything an agent needs to configure a site is in [Options](https://astro-project-site.pascaripavel.workers.dev/docs/reference/options/) (one table, generated from the schema) and [Components](https://astro-project-site.pascaripavel.workers.dev/docs/reference/components/). The whole documentation is also served as markdown at [`/llms.txt`](https://astro-project-site.pascaripavel.workers.dev/llms.txt) (index) and [`/llms-full.txt`](https://astro-project-site.pascaripavel.workers.dev/llms-full.txt) (every page in one file). Options are validated before Astro starts, so a wrong key fails `astro build` with the field's path. --- # Reference URL: https://astro-project-site.pascaripavel.workers.dev/docs/reference/ The tables in this section are **generated from the package source** by this site's own [docs generation](https://astro-project-site.pascaripavel.workers.dev/docs/guides/docs-generation/) (`site/docs-gen.config.mjs`). `npm run build` runs `project-site docs:check`, so a table that no longer matches the code fails the build. | Page | What it covers | |---|---| | [Options](https://astro-project-site.pascaripavel.workers.dev/docs/reference/options/) | Every `projectSite()` option, with type, default and nested shapes | | [Components](https://astro-project-site.pascaripavel.workers.dev/docs/reference/components/) | Everything exported from `astro-project-site/components`, with props and slots | | [Live and runners](https://astro-project-site.pascaripavel.workers.dev/docs/reference/live/) | `` props and the `LiveRunner` / `LiveContext` contract | | [Content collections](https://astro-project-site.pascaripavel.workers.dev/docs/reference/content/) | `projectSiteCollections()`, the gallery schema, docs frontmatter | | [CLI](https://astro-project-site.pascaripavel.workers.dev/docs/reference/cli/) | `project-site init`, `docs:gen`, `docs:check`, `deploy:preview` | | [Theme tokens](https://astro-project-site.pascaripavel.workers.dev/docs/reference/theme-tokens/) | The `--site-*` CSS custom properties | | [Exports and virtual modules](https://astro-project-site.pascaripavel.workers.dev/docs/reference/exports/) | Package entry points, types, `astro-project-site/config` | --- # Quick start URL: https://astro-project-site.pascaripavel.workers.dev/docs/quick-start/ 1. **Create the site.** `init` copies the starter (a complete site that builds) into a new folder and names it after the folder, or after `--name`: ```sh npx astro-project-site@beta init my-lib-site --name "My Lib" ``` ```text Created "My Lib" in /home/you/my-lib-site (29 files). Next: cd my-lib-site npm install npm run dev # http://localhost:4321 ``` It never overwrites an existing file unless you pass `--force`. 2. **Run it.** ```sh cd my-lib-site npm install npm run dev ``` Open `http://localhost:4321`: a landing page, `/docs/`, `/gallery/`, and `/apps/hello/` (a static app served by a mirror). 3. **Make it yours.** Everything about the site is one call in `astro.config.mjs`: ```js title="astro.config.mjs" ins={9-12} // @ts-check import { defineConfig } from 'astro/config'; import projectSite from 'astro-project-site'; export default defineConfig({ integrations: [ projectSite({ name: 'My Lib', tagline: 'Parses things, quickly.', url: 'https://my-lib.dev', repo: 'https://github.com/me/my-lib', install: 'npm i my-lib', externalDocs: [{ dir: './example/docs', route: 'reference', label: 'Reference' }], mirrors: [{ from: './example/apps', to: 'apps' }], }), ], }); ``` A typo fails with the field's name before Astro starts (`unknown option "taglin"`). The dev server restarts by itself when the config changes. All options: [Options](https://astro-project-site.pascaripavel.workers.dev/docs/reference/options/). 4. **Write a docs page.** Add `src/content/docs/docs/usage.md`: ```md title="src/content/docs/docs/usage.md" --- title: Usage description: How to call it. sidebar: order: 1 --- Call `parse()` with a string. ``` It is served at `/docs/usage/`. **Restart the dev server** after adding or removing a page: the sidebar is built at startup. Edits to existing pages reload live. 5. **Build.** ```sh npm run build ``` This runs `astro check`, `astro build` (which fails on a broken link in any docs page) and `project-site docs:check`. The result is static files in `dist/`. `npm run preview` serves them. ## What you got | Path | What it is | |---|---| | `astro.config.mjs` | The site: `projectSite({ … })` | | `src/content.config.ts` | `projectSiteCollections()`: docs, gallery and i18n collections | | `src/content/docs/docs/` | Your docs pages (`.md` / `.mdx`), under `/docs/` | | `src/content/gallery/` | One YAML/JSON/MD file per gallery item | | `example/docs/`, `example/apps/` | Stand-ins for your project's markdown docs and static apps. Point `externalDocs` and `mirrors` at the real ones, then delete `example/` | | `docs-gen.config.mjs` | [Generated blocks](https://astro-project-site.pascaripavel.workers.dev/docs/guides/docs-generation/) in markdown | | `wrangler.jsonc`, `public/_headers` | [Cloudflare Workers](https://astro-project-site.pascaripavel.workers.dev/docs/guides/deploying/) deploy | | `.github/workflows/site.yml` | Only with `init --ci`: checks, a preview per PR, production on `v*` tags ([Deploying](https://astro-project-site.pascaripavel.workers.dev/docs/guides/deploying/#ci-optional)) | `package.json` scripts: `dev`, `build`, `preview`, `check`, `docs:gen`, `docs:check`, `deploy` (`build` + `wrangler deploy`), `deploy:preview`, `cf:dev` (the built site on Cloudflare's local runtime). Next: most libraries already have a repo with a `docs/` folder. [Add the site to it](https://astro-project-site.pascaripavel.workers.dev/docs/existing-repo/). --- # Add it to an existing repo URL: https://astro-project-site.pascaripavel.workers.dev/docs/existing-repo/ Most projects already have a repository with code and a `docs/` folder written for GitHub. The site goes in a folder next to them and reads those files where they are; nothing moves. - my-lib/ - .github/workflows/ - site.yml optional CI (init --ci), calls the reusable workflow - docs/ your markdown, unchanged - README.md - api.md - guides/ - src/ your library - demos/ plain HTML/JS demos - playground/index.html - package.json your library's - website/ **the site** - astro.config.mjs - package.json - package-lock.json - src/content/docs/docs/index.mdx - wrangler.jsonc 1. **Create the site in `website/`.** ```sh cd my-lib npx astro-project-site@beta init website --name "My Lib" cd website && npm install ``` 2. **Mount `../docs` and serve `../` demos.** In `website/astro.config.mjs` replace the `example/` paths: ```js title="website/astro.config.mjs" projectSite({ name: 'My Lib', tagline: 'Parses things, quickly.', url: 'https://my-lib.dev', repo: 'https://github.com/me/my-lib', versionFrom: '../package.json', // the header shows your library's version externalDocs: [ { dir: '../docs', route: 'reference', label: 'Reference', order: ['getting-started.md', 'api.md'], exclude: ['plans/**'] }, ], mirrors: [ // /lib/src/… and /lib/demos/… keep their relative layout, so a demo's `import '../src/x.js'` works. { from: '../', to: 'lib', include: ['src', 'demos'], exclude: ['*.test.js'] }, ], nav: [ { label: 'Docs', href: '/docs/' }, { label: 'Playground', href: '/lib/demos/playground/' }, ], }), ``` - `../docs/README.md` becomes `/docs/reference/`, `../docs/api.md` becomes `/docs/reference/api/`. Relative `.md` links between them are rewritten; a link to `../src/parse.js` goes to the file on GitHub. - "Edit this page" on those pages opens `docs/api.md` in your repo, and on local pages `website/src/content/docs/…`: the integration finds the git root and works out the folder. - The mirror never copies the `website/` folder into itself, nor dotfiles or `node_modules`. Then remove the starter's stand-ins: delete `website/example/`, drop `'example/docs'` from `files` in `website/docs-gen.config.mjs`, and rewrite `src/content/docs/docs/index.mdx` and `src/content/gallery/hello.yaml`, which link to `/apps/…` (the links validator reports the links; the live examples on that page would load nothing). 3. **Optional: CI.** Without it, deploy from your machine with `npm run deploy` ([Deploying](https://astro-project-site.pascaripavel.workers.dev/docs/guides/deploying/)). If you created the site with `--ci`, move the workflow to the repo root; GitHub only reads workflows from the root `.github/`: ```sh mkdir -p .github/workflows && git mv website/.github/workflows/site.yml .github/workflows/site.yml ``` and tell the reusable workflow where the site is: ```yaml title=".github/workflows/site.yml" {4} on: [pull_request, push, workflow_dispatch] jobs: site: uses: pavelpascari/astro-project-site/.github/workflows/deploy.yml@v0.1.0-beta.6 with: { working-directory: website } permissions: { contents: read, pull-requests: write } secrets: CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} ``` If the site is an npm workspace member of the root `package.json` instead (one lockfile at the root), add `install-directory: .`. 4. **Build it.** `npm run build` in `website/`. The build log lists the mirror (`/lib/ ← ../: N files, …`). The links validator now checks every link in your `docs/` folder; fix what it reports (see [Troubleshooting](https://astro-project-site.pascaripavel.workers.dev/docs/recipes/troubleshooting/#the-build-fails-on-a-link)). Next: [deploying](https://astro-project-site.pascaripavel.workers.dev/docs/guides/deploying/) (one-time Cloudflare setup), and if the site must live in its own repository instead, [Separate site repo](https://astro-project-site.pascaripavel.workers.dev/docs/recipes/separate-repo/). --- # Configure the site URL: https://astro-project-site.pascaripavel.workers.dev/docs/guides/configure/ 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](https://astro-project-site.pascaripavel.workers.dev/docs/reference/options/). ## Identity ```js title="astro.config.mjs" 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 /releases install: 'npm i my-lib', // landing page install command with a copy button }), ``` - `url` and `repo` must be full URLs; a trailing slash is dropped. - `repo` on 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. - `versionFrom` is read when the dev server starts (and watched). A file without a `version` logs a warning and shows no version. ## 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`. ```js 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 ```js favicon: '/favicon.svg', // under public/; the default ogImage: '/og.png', // 1200×630 under public/, or a full URL ogImageFor: './src/og.mjs', // per-page images, docs pages included ``` ```js title="src/og.mjs" /** @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 ```js 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 off ``` `linksValidator` takes [starlight-links-validator's options](https://github.com/HiDeoo/starlight-links-validator). 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 ```js theme: { accent: '#c2541b', accentDark: '#ffb347' }, // light theme, dark theme ``` `accentDark` falls back to `accent`. For anything beyond the accent (backgrounds, fonts, radius), override the tokens in CSS: [Theming](https://astro-project-site.pascaripavel.workers.dev/docs/guides/theming/). ## 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: ```js title="docs.config.mjs" /** @type {Partial} */ export default { externalDocs: [{ dir: '../docs', route: 'reference', label: 'Reference' }], }; ``` ```js title="astro.config.mjs" // … projectSite({ ...docs, name: 'My Lib', /* … */ }), ``` ## Using the options in your own pages ```astro title="src/pages/about.astro" --- ---

Version {config.version}. Source: {config.repo}

``` `BaseLayout` gives a page the shared header, footer, theme switch and meta tags. `config` is the validated options (see [Exports](https://astro-project-site.pascaripavel.workers.dev/docs/reference/exports/#astro-project-siteconfig)). --- # Landing page URL: https://astro-project-site.pascaripavel.workers.dev/docs/guides/landing-page/ export const code1 = `

Optional content under the actions.

'} modules={['/docs-assets/status-pill.js']} />
`; export const code2 = `
`; export const code3 = ``; export const code4 = ` `; The page at `/` comes in three levels of control: 1. **Config:** the `landing` option fills the built-in page. Most sites stop here. 2. **Replace the body:** `components.Landing` swaps the page body, keeping the shared header and footer. 3. **Your own page:** `src/pages/index.astro` replaces the injected route; build it from the exported components. `landing: false` removes the page (and its entry from the link validator's known pages). ## From config ```js title="astro.config.mjs" projectSite({ name: 'My Lib', tagline: 'Parses things, quickly.', install: 'npm i my-lib', landing: { hero: { title: 'My Lib', // default: name lead: 'Parses things.', // default: tagline primary: { label: 'Get started', href: '/docs/' }, secondary: { label: 'Gallery', href: '/gallery/' }, demo: { /* a example, see below */ }, }, features: [ { title: 'Small', body: 'One module, no dependencies.' }, { title: 'Typed', body: 'Ships its own types.', href: '/docs/reference/' }, ], steps: { title: 'Three lines', // default "How it works" items: [{ title: 'Install', body: 'Add the package.', code: 'npm i my-lib', lang: 'sh' }], }, gallery: { title: 'See it running', limit: 3 }, // limit: 0 hides the strip cta: { title: 'Ready?', primary: { label: 'Read the docs', href: '/docs/' } }, }, }), ``` The sections render in this order: hero, features, gallery strip, steps, call to action. A section without content is left out: no `features` means no features section; the gallery strip shows when `gallery` is not `false`, the collection has items, and `landing.gallery.limit` is not `0`. `features` and `steps` take an array or `{ title, intro, items }`. Every field: [LandingContent](https://astro-project-site.pascaripavel.workers.dev/docs/reference/options/#landingcontent). ### A live demo in the hero `landing.hero.demo` takes the [`` props](https://astro-project-site.pascaripavel.workers.dev/docs/reference/live/) (except `id`, `head`, `sandbox`, `lazy`, `debounce`, `class`) and renders the example under the hero copy. The demo code is a string: ```js demo: { code: ` `, title: 'hello.html', mode: 'iframe', editable: true, }, ``` For a JSON spec run by your library, set `runner` (see [custom runners](https://astro-project-site.pascaripavel.workers.dev/docs/guides/live-examples/#custom-runners)). ## The components, rendered Everything the built-in page uses is exported from `astro-project-site/components`. Below, each one is rendered by this page at build time, under the code that renders it. Props: [Components](https://astro-project-site.pascaripavel.workers.dev/docs/reference/components/). ### Hero

Optional content under the actions.

'} modules={['/docs-assets/status-pill.js']} />
The `live` slot is a plain, unclipped block under the copy: anything interactive (a canvas, characters walking on the page) can go there. The default slot sits under the actions. ### Section and Features
A feature with `href` gets a real link on its title, and the whole card is clickable. `tone="surface"` tints the section band. ### Steps
Code is highlighted at build time (light and dark themes). ### InstallCommand and CallToAction The copy button appears only where the Clipboard API is available. `GalleryStrip` is shown on the [Gallery](https://astro-project-site.pascaripavel.workers.dev/docs/guides/gallery/#on-the-landing-page) page. ## Replace the body: components.Landing Keep the injected route, the header, footer and meta tags, and write only the body: ```js title="astro.config.mjs" components: { Landing: './src/components/MyLanding.astro' }, ``` ```astro title="src/components/MyLanding.astro" --- const landing = config.landing || {}; ---

…your own section…

``` It renders inside `BaseLayout` and takes no props; read what you need from `astro-project-site/config` (`config.landing` has `features` and `steps` normalised to `{ title, intro, items }`). ## Your own page: src/pages/index.astro A file at `src/pages/index.astro` (or `index.md`, `index.mdx`, `index.html`) replaces the injected `/` route; the build logs `src/pages/index.astro replaces the built-in / page.` Use `BaseLayout` to keep the shared header, footer and theme: ```astro title="src/pages/index.astro" --- ---
``` `BaseLayout` without a `title` gives the page "Name — tagline" as its title. On a `BaseLayout` page the `site-container` (centred, max width) and `site-btn` / `site-btn--primary` classes are available. `} /> --- # Docs URL: https://astro-project-site.pascaripavel.workers.dev/docs/guides/docs/ The docs are Starlight, fed from two places: - **Local pages** in `src/content/docs/docs/`, `.md` or `.mdx` with frontmatter, served under `/docs/`. - **Mounted folders** (`externalDocs`): plain markdown that lives elsewhere, usually your repo's `docs/` (or a folder of [another repository](#mount-another-repository)), served under `/docs//`. These files need no frontmatter and stay readable on GitHub. Both are one Starlight collection: search, the links validator, edit links, `llms.txt` and the sidebar treat them alike. ## Local pages ```md title="src/content/docs/docs/usage.md" --- title: Usage description: Shown in search results, meta tags and llms.txt. sidebar: order: 2 --- Body in Markdown. In `.mdx` you can import components. ``` - `src/content/docs/docs/index.mdx` is `/docs/`; `usage.md` is `/docs/usage/`; `guides/setup.md` is `/docs/guides/setup/`. - All of [Starlight's frontmatter](https://starlight.astro.build/reference/frontmatter/) and [components](https://starlight.astro.build/components/using-components/) work. Add fields with [`docsExtend`](https://astro-project-site.pascaripavel.workers.dev/docs/reference/content/). - Link to other pages with **root-relative** paths (`/docs/usage/`, `/docs/usage/#options`). The links validator rejects relative links (`./usage/`) in local pages. - Files and folders starting with `_` are not pages; use them for partials and components (this site keeps a helper component in `src/content/docs/_components/`). ## The sidebar The sidebar is generated when the dev server starts, so **restart it after adding, removing or renaming a page**. Edits to existing pages, local or mounted, reload live. 1. **Top-level local pages** of `src/content/docs/docs/`: `index` first, then by `sidebar.order`, then by file name. `sidebar.hidden: true` leaves a page out. 2. **One group per `externalDocs` entry**, labelled with its `label`. 3. **One collapsed group per local subfolder**, in folder-name order, labelled from the folder name (`getting-started/` → "Getting started"), with Starlight's `autogenerate` inside, so pages are ordered by `sidebar.order` then name. A group opens when it holds the current page. This site's sidebar is exactly that: three top-level pages, the mounted example folder, then `guides/`, `recipes/` and `reference/`. Groups 2 and 3 are the docs **sections**. To put them in another order, for example a hands-on guide of your own before the mounted reference, list them in `docsOrder`, by mount `route` and local folder name: ```js title="astro.config.mjs" projectSite({ // ... externalDocs: [{ dir: '../docs', route: 'reference', label: 'Reference' }], docsOrder: ['guide', 'reference'], // src/content/docs/docs/guide/ first }); ``` The listed sections come first, in that order, and the others follow in the order above. The cards on the docs index and on the landing page follow the same order. A name that is not a section fails the build with the list of section names. To add links after the generated items, pass Starlight's `sidebar` through; it is appended: ```js starlight: { sidebar: [{ label: 'Changelog', link: 'https://github.com/me/my-lib/releases' }], }, ``` ## Mount markdown from elsewhere ```js title="astro.config.mjs" externalDocs: [ { dir: '../docs', // relative to the project root; may be outside it route: 'reference', // → /docs/reference/… (nested routes like 'api/v2' work) label: 'Reference', // sidebar group description: 'Every API, flag and file format.', // its card; else the README's first paragraph order: ['getting-started.md', 'api.md'], // listed first, in this order (.md optional) exclude: ['plans/**', 'drafts/*.md'], // globs relative to dir }, ], ``` Given this folder: - docs/ - README.md - getting-started.md - api.md - SPEC.md - guides/ - README.md - deploying.md - plans/ - roadmap.md excluded | File | URL | Sidebar | |---|---|---| | `README.md` | `/docs/reference/` | "Overview", first | | `getting-started.md`, `api.md` | `/docs/reference/getting-started/`, `/docs/reference/api/` | in `order` | | `SPEC.md` | `/docs/reference/spec/` | then by file name | | `guides/README.md` | `/docs/reference/guides/` | a collapsed group named after its H1 | | `guides/deploying.md` | `/docs/reference/guides/deploying/` | inside that group | What happens to each file: - **Only `.md`** files are mounted (not `.mdx`). Dot-folders and `node_modules` are skipped, and so is anything matching `exclude` (`**`, `*` and `?` are supported). - **URL:** the path without `.md`, each segment lowercased with spaces turned into dashes and punctuation dropped. `README.md` and `index.md` are their folder's page. - **Title:** frontmatter `title`, else the first `# H1` (which is then removed from the body, so it is not shown twice), else the file name. - **Description:** frontmatter `description`, else the first paragraph before any heading, cut to one sentence. - **Links:** relative links to `.md` files (or to a folder with a `README.md`) in any mount become site URLs; an `#anchor` pointing at the target's H1 is dropped. Relative links to anything else in the repo (source files, folders, markdown outside every mount) go to GitHub: `/blob//` (`/tree/` for folders). Absolute URLs, `/root` paths, `#anchors`, images and code are left alone. - **Edit link:** `/edit//`. - **Starlight markdown** (`:::note` asides, heading anchors) works in mounted folders too. - In dev the folder is watched: saving `../docs/api.md` reloads the page. You can see it in the deployed starter: its [Reference](https://project-site-starter.pascaripavel.workers.dev/docs/reference/) is the starter's `example/docs/` folder, plain GitHub-flavoured markdown with relative links. Compare [its source](https://github.com/pavelpascari/astro-project-site/tree/main/starters/default/example/docs). ## Mount another repository Give `git` instead of `dir`, and the build downloads that folder of another repository and mounts it: ```js title="astro.config.mjs" externalDocs: [ { git: { repo: 'https://github.com/org/other-lib', // https://, ssh://, git@host:owner/repo or file:// ref: 'v1.4.0', // a tag, a branch or a full commit SHA path: 'docs', // the folder in that repository; default: its root }, route: 'other-lib', label: 'Other lib', // description, order, exclude and include work as with `dir` }, ], ``` Everything above applies to the downloaded files: titles, URLs, the sidebar, link rewriting, search and `llms.txt`. What differs: - **Download.** At startup (`astro dev`, `astro build`, `astro check`), with the `git` command: a shallow fetch of `path` only, at `ref`, without history. It is cached in Astro's cache folder (`node_modules/.astro/` unless you set `cacheDir`). - **`ref`.** A tag or commit is downloaded once and reused, so later builds work offline and give the same pages. A branch is downloaded again on every start, with a warning, because the docs change when it moves; if that fails, the build uses the last copy and says so. - **Links** from those pages to files that are not mounted (source files, folders, the repository's README) go to **that** repository, at `ref`: `https://github.com/org/other-lib/blob/v1.4.0/src/parse.js`. Links that leave the repository are left as written. - **Edit link:** that repository's default branch, `https://github.com/org/other-lib/edit/main/docs/…`: the docs are pinned, but edits go where the docs are written. A `file://` source has no web page, so it gets neither GitHub links nor edit links. - **Private repositories:** over `https://github.com/…`, the build sends `GITHUB_TOKEN` from the environment when it is set (as a header; it is not written to disk or to the logs). Elsewhere, use an `ssh://` or `git@…` URL and your SSH key, or a URL your git credential helper knows. A token inside the URL (`https://user:token@…`) is refused: it would be printed in build logs. The [CI workflow](https://astro-project-site.pascaripavel.workers.dev/docs/guides/deploying/#ci-optional) does not hand its secrets to the build, where every dependency could read them: for a private repository in CI, check it out with `source-repo` and mount it with `dir` (see [Separate site repo](https://astro-project-site.pascaripavel.workers.dev/docs/recipes/separate-repo/)). - **Symlinks** in the downloaded repository are checked out as plain files holding the link's path, so they cannot pull files of the build machine into the site. - **Errors** name the entry: an unknown tag or branch, a short SHA, a folder that is not there, or no `git` command fail the build with that message. To show newer docs, change `ref` (Dependabot does not see it: bump it when you release the other project). In dev the downloaded folder is not watched; restart to pick up a new `ref`. ## Edit links - Local pages: Starlight's `editLink.baseUrl` is set to `/edit///`, so a site in `website/` links to `website/src/content/docs/…`. - Mounted pages: each page's `editUrl` points at its own file (for a `git` source, in that repository's default branch). - Turn one off with frontmatter `editUrl: false`; replace the local base with `starlight: { editLink: { baseUrl } }`. ## Search, llms.txt, 404 - **Search** is Starlight's Pagefind, built with `astro build` (so `npm run dev` has no search index). It covers local and mounted pages. `starlight: { pagefind: false }` turns it off, and the header hides the box. - **`/llms.txt`** lists every docs page (title, URL, description) grouped like the sidebar; **`/llms-full.txt`** is every page's markdown in one file with root links made absolute. `llms: false` turns both off. - **404:** a default "Page not found" page is built unless you add `src/content/docs/404.md`. ## Pages outside /docs/ Starlight pages anywhere in `src/content/docs/` work (`src/content/docs/changelog.md` → `/changelog/`), but the generated sidebar and `llms.txt` only cover `/docs/`. --- # Live examples URL: https://astro-project-site.pascaripavel.workers.dev/docs/guides/live-examples/ `` turns one piece of code into a code block **and** its running result. The component reads the source back from the rendered code block, so what runs is exactly what is shown (and, when editable, what the reader typed). Every example on this page is a ``; the modules they load are in this site's `public/docs-assets/`. All props: [Live and runners](https://astro-project-site.pascaripavel.workers.dev/docs/reference/live/). ## Write one In MDX, put a fenced code block inside ``, with a blank line after the opening tag and before the closing one. MDX never touches the inside of a fence, so ` ``` ```` ```html title="pill.html" ``` The fence's `title="…"` and other Expressive Code meta work as usual. Serve the modules your examples load from `public/` or from a [mirror](https://astro-project-site.pascaripavel.workers.dev/docs/guides/mirrors/) of your library's source (`/lib/src/index.js`). In `.astro` files, or for code kept in a file, pass `code` instead (with `lang` and `title`): ```astro --- --- ``` \n`} title="from-a-prop.html" caption="Source passed as the code prop" /> ## Inline mode (default): part of the page `mode="inline"` renders into the page. Scripts run, classic and module, inline and external. Modules are evaluated once per page (the browser's module map), so two examples loading the same custom element do not define it twice; external classic scripts are de-duplicated the same way. Inline examples share the page: they can read and change it, a `" > ```html

The frame grows with its content.

    ```
    Errors in the iframe (exceptions, rejected promises, a script or stylesheet that fails to load) are shown under the preview. ## Editable `editable` turns the code into a text area. Edits re-run the example after `debounce` ms (300 by default), the copy button copies what was typed, and **Reset** restores the original. Tab inserts two spaces; Escape then Tab leaves the editor. Editable HTML is best in an iframe, which starts from a clean document on every run. ```html

    Try tone="green" or tone="red".

    ```
    ## Custom runners With `runner="/url/of/module.js"` the source is not HTML: it is handed to the module's `run(source, mount, ctx)`, which renders it. That is how a library shows its own format (a chart spec, a config, a small language) running. The code defaults to `lang="json"`. ```js title="public/docs-assets/runners/bar-chart.js (abridged)" /** @type {import('astro-project-site').LiveRunner} */ export function run(source, mount, ctx) { const spec = JSON.parse(source); // throw → the error shows under the preview const limit = Number(ctx.options.max ?? 12); // the `options` prop // …build an from spec.bars, coloured for ctx.theme, animated unless ctx.reducedMotion… mount.append(svg); ctx.status(`${n} bars`, 'ok'); // one line under the preview return () => animations.forEach((a) => a.cancel()); // cleanup before the next run } ``` ````mdx ```json title="downloads.json" { "title": "Weekly downloads", "unit": "k", "bars": { "mon": 4, "tue": 7 } } ``` ```` ```json title="downloads.json" { "title": "Weekly downloads", "unit": "k", "bars": { "mon": 4, "tue": 7, "wed": 9, "thu": 6, "fri": 11 } } ``` Add a sixth and seventh bar to see the `max` option's warning; switch the theme to see it re-run with `ctx.theme`. When `run` throws, the error is shown and the last good render stays: ```json { "bars": { "ok": 3, "broken": "seven" } } ``` The runner contract (`LiveContext`, when it re-runs, cleanup): [Live and runners](https://astro-project-site.pascaripavel.workers.dev/docs/reference/live/#runner-modules). In iframe mode the runner module is loaded inside the iframe once; later edits only call `run` again. ## Layout - `preview="above"` (default), `"below"` or `"side"` (side by side from about 36rem of width, stacked below that). - `caption` adds a caption with a `#` link. The anchor is `id`, else derived from the caption or title (`#live-…`), else from a hash of the source. - `height` is the preview's minimum height (number = px), which avoids layout shift; in iframe mode also the frame's height before it measures itself. - `lazy` starts the example only when it scrolls near the viewport. ```html

    The preview can sit under the code, too.

    ```
    ## Outside the docs `` works on any `BaseLayout` page and in the landing hero (`landing.hero.demo`): `theme.css` supplies the `--sl-*` tokens it uses outside Starlight. Its styles are scoped under `live-example`. --- # Markdown URL: https://astro-project-site.pascaripavel.workers.dev/docs/guides/markdown/ Point the site at the `.md` files already in your repository and they render at least as well as on GitHub: the same syntax, the same heading anchors, nothing to rewrite. This page is a plain `.md` file and shows each feature as its source, then the result. It works on every page that renders markdown: local docs pages (`.md` and `.mdx`), folders mounted with `externalDocs`, blog posts, and your own pages. Nothing to install or configure; [each extra can be switched off](#options). ## Text ````md **Bold**, *italic*, ***both***, ~~strikethrough~~, `inline code`, H2O, x2, Ctrl + K, and emoji shortcodes :tada: :rocket: :+1:. Bare links become links: www.example.com, https://astro.build/ and docs@example.com. ```` **Bold**, *italic*, ***both***, ~~strikethrough~~, `inline code`, H2O, x2, Ctrl + K, and emoji shortcodes :tada: :rocket: :+1:. Bare links become links: www.example.com, https://astro.build/ and docs@example.com. Emoji use GitHub's names (the [gemoji](https://github.com/github/gemoji) list); an unknown `:name:` stays as typed, and code is never touched. Quotes and `...` become typographic; `--` stays as typed, as on GitHub, so CLI flags in prose survive. ## Headings and anchors Every heading gets an id made the way GitHub makes it (lowercase, spaces to dashes, punctuation dropped, `-1`, `-2`… for repeats), so a `#fragment` link copied from GitHub lands on the same heading here. Hover a heading for its link. This section is [`#headings-and-anchors`](#headings-and-anchors), as on GitHub. ## Lists and task lists ````md 1. First 2. Second - nested - [x] done, a task inside a list - [x] Write the docs - [ ] Ship it - [ ] Announce it ```` 1. First 2. Second - nested - [x] done, a task inside a list - [x] Write the docs - [ ] Ship it - [ ] Announce it Task lists render as checkboxes that cannot be clicked, as on GitHub outside issues. ## Tables Column alignment with `:--`, `:-:` and `--:`. A table wider than the column scrolls in its own box (with a tab stop, so the keyboard can scroll it too), never the page. ````md | Left | Centre | Right | | :--- | :----: | ----: | | `a` | b | 1 | | long cell text | ✓ | 1,024 | ```` | Left | Centre | Right | | :--- | :----: | ----: | | `a` | b | 1 | | long cell text | ✓ | 1,024 | | Option | Type | Default | Applies to | Since | Description | | --- | --- | --- | --- | --- | --- | | `markdown.alerts` | `boolean` | `true` | every markdown page | 0.2.0 | GitHub alert blockquotes become callouts with an icon and a title. | | `markdown.mermaid` | `boolean` | `true` | every markdown page | 0.2.0 | Mermaid code blocks are drawn as diagrams in the browser, lazily. | | `markdown.math` | `boolean` | `true` | every markdown page | 0.2.0 | Dollar-sign math and math code blocks are typeset with KaTeX at build time. | ## Alerts GitHub's five alerts. The marker goes alone on the first line of a blockquote. ````md > [!NOTE] > Useful information that users should know, even when skimming content. > [!TIP] > Helpful advice for doing things better or more easily. > [!IMPORTANT] > Key information users need to know to achieve their goal. > [!WARNING] > Urgent info that needs immediate user attention to avoid problems. > [!CAUTION] > Advises about risks or negative outcomes of certain actions. ```` > [!NOTE] > Useful information that users should know, even when skimming content. > [!TIP] > Helpful advice for doing things better or more easily. > [!IMPORTANT] > Key information users need to know to achieve their goal. > [!WARNING] > Urgent info that needs immediate user attention to avoid problems. > [!CAUTION] > Advises about risks or negative outcomes of certain actions. An alert can hold anything a blockquote can: paragraphs, lists, code. A blockquote without a marker stays a blockquote: > Just a quote. **Markdown** still works in it. In docs pages Starlight's own `:::note` / `:::tip` / `:::caution` / `:::danger` asides work too; alerts are the syntax that also renders on GitHub. ## Footnotes ````md Footnotes are numbered in order of use[^first], can be referenced again[^first], and can hold formatting[^long]. [^first]: The first footnote. [^long]: A longer one, with `code` and a [link](https://github.com/). ```` Footnotes are numbered in order of use[^first], can be referenced again[^first], and can hold formatting[^long]. [^first]: The first footnote. [^long]: A longer one, with `code` and a [link](https://github.com/). They are listed at the end of the page under "Footnotes", each with a link back to where it was used. ## Collapsed sections ````md
    Click to expand Markdown works inside, after a blank line: **bold**, lists, code. ```js console.log('hidden until opened'); ```
    ````
    Click to expand Markdown works inside, after a blank line: **bold**, lists, code. ```js console.log('hidden until opened'); ```
    ## Images ````md ![A relative image](./markdown-assets/relative.svg) ![An image from public/](/markdown-assets/public.svg) ```` ![A relative image](./markdown-assets/relative.svg) ![An image from public/](https://astro-project-site.pascaripavel.workers.dev/markdown-assets/public.svg) Relative paths are resolved from the markdown file (and optimised at build time), so images next to your README keep working when the folder is mounted with `externalDocs`. ## Math Typeset with [KaTeX](https://katex.org/) at build time: no JavaScript in the page, and KaTeX's stylesheet is linked only from pages that contain math. ````md Inline: $e^{i\pi} + 1 = 0$, and the area of a circle is $A = \pi r^2$. $$ \int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi} $$ ```math \begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \times \mathbf{B} &= \mu_0 \mathbf{J} + \mu_0 \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \end{aligned} ``` ```` Inline: $e^{i\pi} + 1 = 0$, and the area of a circle is $A = \pi r^2$. $$ \int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi} $$ ```math \begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \times \mathbf{B} &= \mu_0 \mathbf{J} + \mu_0 \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \end{aligned} ``` Wide formulas scroll sideways in their own box. A typo in a formula shows the source in red instead of failing the build. Screen readers get MathML. ## Code blocks Code blocks use [Expressive Code](https://expressive-code.com/) with every language [Shiki](https://shiki.style/languages) knows; an unknown language renders as plain text with a build warning, never an error. Each block has a copy button, and blocks whose lines do not fit get a **wrap lines** toggle (try this page on a phone). ### Titles and frames ````md ```js title="src/greet.js" export const greet = (name) => `Hello, ${name}!`; ``` ```ts // src/config.ts export const retries = 3; ``` ```` ```js title="src/greet.js" export const greet = (name) => `Hello, ${name}!`; ``` ```ts // src/config.ts export const retries = 3; ``` A first-line comment that looks like a file name becomes the title, as above. ### Terminals and prompts Shell languages (`bash`, `sh`, `zsh`, `shell`, `powershell`) get a terminal frame. A `$ ` prompt cannot be selected and is not copied; when a block mixes commands and output, the copy button copies only the commands. ````md ```bash # Comments are not copied either npm create astro@latest -- --template minimal ``` ```sh $ npx astro-project-site@beta init my-site ``` ```console $ npm install astro-project-site added 312 packages in 9s $ npx astro-project-site@beta init my-site --name "My Lib" Created my-site/ (14 files) ``` ```` ```bash # Comments are not copied either npm create astro@latest -- --template minimal ``` ```sh $ npx astro-project-site@beta init my-site ``` ```console $ npm install astro-project-site added 312 packages in 9s $ npx astro-project-site@beta init my-site --name "My Lib" Created my-site/ (14 files) ``` ### Diffs ````md ```diff - const answer = 41; + const answer = 42; console.log(answer); ``` ```diff lang="ts" function total(items: Item[]) { - return items.reduce((a, b) => a + b.price, 0); + return items.reduce((sum, item) => sum + item.price * item.quantity, 0); } ``` ```js ins={2} del={1} "price" const total = items.length * price; const total = items.reduce((sum, item) => sum + item.price, 0); ``` ```` ```diff - const answer = 41; + const answer = 42; console.log(answer); ``` ```diff lang="ts" function total(items: Item[]) { - return items.reduce((a, b) => a + b.price, 0); + return items.reduce((sum, item) => sum + item.price * item.quantity, 0); } ``` ```js ins={2} del={1} "price" const total = items.length * price; const total = items.reduce((sum, item) => sum + item.price, 0); ``` A plain `diff` block colours `+` and `-` lines; `diff lang="ts"` also highlights the code. The copy button copies the code without the `+`/`-` markers. ### Highlighting, line numbers, collapsing, wrapping ````md ```astro {2} "Astro.props" showLineNumbers collapse={7-9} --- const { title } = Astro.props; --- ``` ```txt wrap A long line of plain text that wraps instead of scrolling, because the block asks for it with the wrap option in its meta string. ``` ```` ```astro {2} "Astro.props" showLineNumbers collapse={7-9} --- const { title } = Astro.props; --- ``` ```txt wrap A long line of plain text that wraps instead of scrolling, because the block asks for it with the wrap option in its meta string. ``` ```js // A long line without `wrap`: on a narrow screen the block scrolls, and a "Wrap lines" button appears next to the copy button. const url = new URL('/docs/guides/markdown/#code-blocks', 'https://astro-project-site.pascaripavel.workers.dev').toString(); ``` ### Meta syntax What goes after the language on the opening fence: | Meta | Effect | | --- | --- | | `title="file.js"` | Title in the frame (a first-line `// file.js` comment does the same) | | `frame="terminal"`, `frame="code"`, `frame="none"` | Choose the frame instead of the automatic one | | `{2}`, `{1,4-6}` | Highlight lines | | `ins={2}`, `del={3-4}` | Mark lines as inserted or deleted | | `"word"`, `/regex/` | Highlight text; `ins="…"`, `del="…"` for inserted/deleted text | | `lang="ts"` on a `diff` block | Diff markers plus highlighting for that language | | `showLineNumbers`, `startLineNumber=10` | Line numbers (off by default, as on GitHub) | | `collapse={1-5}` | Collapse lines behind a "N collapsed lines" toggle | | `wrap` | Wrap long lines instead of scrolling | ### Languages Every Shiki language works. Common ones, by the names GitHub uses: | Kind | Languages | | --- | --- | | Shell | `bash`, `sh`, `zsh`, `shell`, `powershell`/`ps1`, `console`/`shell-session` (prompts and output), `bat` | | Data and config | `json`, `jsonc`, `json5`, `yaml`, `toml`, `ini`, `xml`, `csv`, `env`/`dotenv`, `properties` | | Web | `js`, `ts`, `jsx`, `tsx`, `astro`, `html`, `css`, `scss`, `vue`, `svelte`, `graphql`, `http` | | Docs | `md`, `mdx`, `diff`, `text`/`txt`/`plaintext`, `math` (typeset), `mermaid` (drawn) | | Systems and backend | `python`, `go`, `rust`, `java`, `kotlin`, `c`, `cpp`, `csharp`, `ruby`, `php`, `swift`, `sql` | | Ops | `dockerfile`, `nginx`, `terraform`/`hcl`, `make`, `proto` | ```text Plain text: no highlighting, still a copy button. ``` ```http GET /docs/ HTTP/2 Accept: text/html ``` ```python def fib(n: int) -> int: return n if n < 2 else fib(n - 1) + fib(n - 2) ``` ```rust fn main() { println!("Hello from {}", env!("CARGO_PKG_NAME")); } ``` ## Mermaid diagrams A `mermaid` code block becomes a diagram. Mermaid loads only on pages that have one, only when a diagram scrolls near, and draws in the site's colours (switch the theme to see it redraw). Wide diagrams keep a readable size and scroll sideways. The source stays under each diagram, and is what shows if a diagram cannot be drawn (or before JavaScript runs). Mermaid is an optional dependency, because it is large (about 127 MB in `node_modules`). Install it in your site to draw diagrams: ```bash npm i mermaid ``` `project-site init` adds it for you when your repository's markdown already has a `mermaid` block. Without it, diagrams show their source with a note saying how to draw them, and the build prints one warning naming the first file that has one; set `markdown: { mermaid: false }` to silence that. ````md ```mermaid flowchart LR md[Your .md files] --> site[astro-project-site] site --> docs[Docs] & blog[Blog] & llms[llms.txt] ``` ```` ```mermaid flowchart LR md[Your .md files] --> site[astro-project-site] site --> docs[Docs] & blog[Blog] & llms[llms.txt] ``` ```mermaid sequenceDiagram autonumber participant B as Browser participant S as Site B->>S: GET /docs/guides/markdown/ S-->>B: HTML (diagram source inside) B->>B: scrolls near a diagram B->>S: GET mermaid chunk S-->>B: JavaScript Note over B: draws the SVG in the site's colours ``` ```mermaid classDiagram class Page { +string title +render() HTML } class DocsPage class BlogPost { +Date date } Page <|-- DocsPage Page <|-- BlogPost ``` ```mermaid stateDiagram-v2 [*] --> Source Source --> Pending: scrolls near Pending --> Drawn: parsed Pending --> Error: invalid Drawn --> Drawn: theme switch Error --> [*] ``` ```mermaid erDiagram PROJECT ||--o{ PAGE : has PAGE ||--o{ HEADING : contains PAGE }o--o{ TAG : "tagged with" ``` ```mermaid gantt title Release plan dateFormat YYYY-MM-DD axisFormat %b %d tickInterval 1week section Docs Write guides :done, d1, 2026-01-05, 7d Review :active, d2, after d1, 4d section Site Markdown parity :crit, s1, 2026-01-08, 9d Launch :milestone, after s1, 0d ``` ```mermaid pie title Where the bytes go "HTML" : 42 "CSS" : 18 "JavaScript" : 25 "Fonts" : 15 ``` ```mermaid mindmap root((Markdown)) GitHub syntax Alerts Task lists Footnotes Extras Math Diagrams Emoji ``` ```mermaid timeline title astro-project-site 2025 : First landing page 2026 : Docs mounting : Markdown parity Next : Blog ``` ```mermaid gitGraph commit branch feature checkout feature commit commit checkout main merge feature commit ``` A wide diagram: ```mermaid flowchart LR a[Write markdown] --> b[Commit] --> c[Open a pull request] --> d[CI builds the site] --> e[Preview deploy] --> f[Review] --> g[Merge] --> h[Production deploy] --> i[Readers] ``` A diagram with a mistake shows its source and a note instead: ```mermaid flowchart LR a --> this is not mermaid ``` Diagrams use Mermaid's classic `dagre` layout. Its optional ELK engine is EPL-licensed and not bundled, so a diagram that asks for `layout: elk` shows its source instead. Give a diagram an accessible title and description with Mermaid's `accTitle:` and `accDescr:` lines; without them it is announced by its type, and its source is available under "Diagram source". ## Raw HTML HTML in markdown is passed through as written, as GitHub does for the tags it allows (`
    `, ``, ``, ``, ``, `
    `, alignment attributes, comments…). Unlike GitHub, nothing is stripped: the markdown is your own repository's, so ` ``` ```js components: { Footer: './src/components/Footer.astro' }, ``` If your `_headers` has a strict `Content-Security-Policy`, allow the analytics origin in `script-src` and `connect-src`. --- # Languages URL: https://astro-project-site.pascaripavel.workers.dev/docs/recipes/i18n/ ## A site in another language Set the language once, as Starlight's root locale: ```js title="astro.config.mjs" projectSite({ // ... starlight: { locales: { root: { label: 'Français', lang: 'fr' } } }, }); ``` Every page follows it, the landing page, gallery and blog included: - `` everywhere, and `dir="rtl"` for a right-to-left language (`dir: 'rtl'` in the locale). - Starlight's own words (search, "On this page", pagination) in French, from Starlight. - The template's own words in French: "Copier", "Aller au contenu", the theme switch, the gallery filters, "Voir toute la galerie", reading time, dates, "Ada et Grace" for two authors, alert titles (`> [!NOTE]` is "Remarque"), the default nav and section headings. Built-in translations: **English, French, German and Spanish**. Any other language gets English for the template's words until you set them (below); a regional tag (`pt-BR`, `fr-CA`) uses its language's translation. Your own text (options, docs, posts, gallery entries) is whatever language you write it in. ## Change the template's words `labels` sets any of them, by name, in any language. For example, in Portuguese: ```js title="astro.config.mjs" projectSite({ // ... starlight: { locales: { root: { label: 'Português', lang: 'pt' } } }, labels: { copy: 'Copiar', skipToContent: 'Ir para o conteúdo', // Counted words take plural forms (Intl.PluralRules categories; `other` is required). pageCount: { one: '{n} página', other: '{n} páginas' }, }, }); ``` It works in English too, to change a word you would rather not use (`labels: { galleryAll: 'More demos' }`). Every name, with its English text, is in [`src/labels.mjs`](https://github.com/pavelpascari/astro-project-site/blob/main/packages/astro-project-site/src/labels.mjs); an unknown name is a build error, so a typo does not go unnoticed. `{n}`, `{year}`, `{name}`, `{tag}` and the other placeholders are filled in for you. A few words are options of their own, because they are content rather than interface: section headings (`landing.features.title`, `landing.docs.title`, `blog.title`, `gallery.title`), the footer's copyright line (`footer.copyright`, `{year}` and `{name}` filled in) and the nav (`nav`). ## Right-to-left languages With `dir: 'rtl'`, the layout mirrors: the header, cards, arrows ("All posts ←"), the theme switch and the margin notes. Shell commands and code stay left to right. The template's styles use logical properties only (`margin-inline-start`, not `margin-left`); a test keeps it that way. ## Multilingual sites Starlight's multi-locale setup (several `locales` and `src/content/docs//` folders) passes through, and docs pages in a second locale get the template's words in that language (its built-in translation, or English), except alert titles, which markdown renders once, in the root language. The generated sidebar only reads `src/content/docs/docs/`, though, so translated pages need a hand-written `starlight.sidebar`; the landing page, gallery, blog and `llms.txt` are in the root language only. This is not tested yet. ## How it is checked The repository builds a small site in French and in Arabic (right to left) on every change (`npm run test:i18n`): each page must carry the right `lang` and `dir`, show the translated words and none of the English they replace, and pass the same accessibility checks as the template's own site. --- # Accessibility URL: https://astro-project-site.pascaripavel.workers.dev/docs/recipes/accessibility/ The template aims at WCAG 2.2 AA on every page it renders: the landing page, docs, gallery and blog. ## What you get without doing anything - **Keyboard:** a "Skip to content" link, visible focus rings, `/` to filter a long docs sidebar, menus that close on Escape and give focus back, and live-example editors you can leave with Escape then Tab. - **Screen readers:** one `

    ` and a `
    ` per page; every landmark, button and link has a name (copy buttons included, not just a tooltip); status messages ("Copied", "3 pages match", the gallery count) are announced; external gallery links say "(external site)"; decorative icons are hidden. - **Low vision:** text, links, buttons and focus rings meet WCAG 2.2 AA contrast in both themes; with "Increase contrast" turned on in the system, secondary text goes to 7:1. Zooming is never blocked, and pages reflow down to 320 px wide without scrolling sideways. - **Touch:** targets are at least 44×44 px on touch screens. - **Language:** `` and `dir` on every page, and the template's words in the site's language (see [Languages](https://astro-project-site.pascaripavel.workers.dev/docs/recipes/i18n/)). ## What is yours to look after Your content: alt text for images in posts and gallery posters (`posterAlt`), headings in order, link text that says where it goes, and captions for video. A custom `theme.accent` is checked for contrast at build time (see [Theming](https://astro-project-site.pascaripavel.workers.dev/docs/guides/theming/)); colours you set in `customCss` are not. ## How it is checked On every change, CI: 1. builds the template's own site and the starter, then runs html-validate's accessibility rules and checks of its own (lang, one `

    `, a `
    `) on every page: `npm run test:a11y`; 2. builds a small site in French and in Arabic (right to left) and runs the same checks, plus the language ones: `npm run test:i18n`; 3. checks the theme's colour pairs against WCAG 2.2 AA in both themes, and that no component has English text written into it (`npm test`). A handful of findings in Starlight's own markup (its two tables of contents share a name, as only one is shown at a time) are listed, with the reason, in `scripts/check-html.mjs`. Layout at different screen sizes and in three browsers is checked by the UX harness described in `CONTRIBUTING.md`. --- # Troubleshooting URL: https://astro-project-site.pascaripavel.workers.dev/docs/recipes/troubleshooting/ ## The build fails on a link `astro build` runs [starlight-links-validator](https://github.com/HiDeoo/starlight-links-validator) over every docs page, local and mounted, and stops on a broken internal link or `#anchor`: ```text validating links ╭─ docs/quick-start.mdx · 117 | /docs/guides/docs-generation/ · ╰── invalid link ╭─ ─╮ · Found 1 invalid links in 1 files. · ╰─ ─╯ ``` | Report | Cause | Fix | |---|---|---| | invalid link to a docs page | The page does not exist, or was renamed | Fix the path. Mounted files: link the `.md` file, not the URL | | invalid hash | No heading with that slug on the target | Slugs are the lowercased heading text, spaces → `-`, punctuation dropped (`## The CLI!` → `#the-cli`) | | relative link (local page) | `./usage/` or `../guides/` in a page under `src/content/docs/` | Use root-relative links: `/docs/usage/` | | relative link (mounted page) | A link to a file outside the git repo the site is in (see [Separate site repo](https://astro-project-site.pascaripavel.workers.dev/docs/recipes/separate-repo/#limits-of-a-second-checkout)) | Mount it with a [`git` source](https://astro-project-site.pascaripavel.workers.dev/docs/guides/docs/#mount-another-repository); else an absolute URL, or `linksValidator: { errorOnRelativeLinks: false }` | | link to a page of your own (`/about/`) | The validator only knows docs pages; the landing page, `/gallery/`, `/llms*.txt` and mirror prefixes are pre-registered | `linksValidator: { exclude: ['/about/', '/blog/**'] }` | Links to other sites are not checked. `linksValidator: false` turns the check off (not recommended). ## A new page is not in the sidebar The sidebar is built when the dev server starts. Restart `npm run dev` after adding, removing or renaming a page. If it still is not there: a top-level page with `sidebar.hidden: true`, a file or folder starting with `_`, a local folder named like an `externalDocs` route, or (mounted) a non-`.md` file or an `exclude` match. ## Mirror errors ```text [mirror] mirrors[0] (../) would overwrite /index.html, which the site itself builds. Change `to` or exclude the file. ``` A mirrored file lands on a path the site builds (a page, something in `public/`). Mirror under a prefix no page uses, or `exclude` the file. Two mirrors writing the same file only warn (the later one wins). ```text [mirror] mirrors[0].from "../my-lib" resolves to /home/runner/work/…/my-lib, which is not a folder. ``` Paths are relative to the project root. In CI, the folder may need a [`source-repo`](https://astro-project-site.pascaripavel.workers.dev/docs/recipes/separate-repo/#in-ci-source-repo) checkout. A mirror that matches nothing only warns: check `include`. ## Edit links point to the wrong place Edit links are `/edit//`. The git root is the nearest folder with a `.git`. **Before `git init`** (straight after `project-site init`) the project root is taken as the repo root, so links lack a `website/` prefix until the folder is inside a repository. Also check `repoBranch` (default `main`), and that `repo` is the repository holding the site. For mounted folders outside the site's repo there is no edit link. ## Option errors ```text Invalid projectSite() options: - landing.hero.primary.href: Invalid input: expected string, received undefined - unknown option "navv" ``` Each line names the field. Paths that must exist are checked too: `customCss[0]: "./src/brand.css" resolves to /…/src/brand.css, which does not exist (paths are relative to the project root)`. ## "No cached compile metadata found" The package was installed as a `file:` link to a folder outside the project (for example a clone of this repo), so it resolves a second copy of Astro. Install from the registry or from an `npm pack` tarball ([Quick start](https://astro-project-site.pascaripavel.workers.dev/docs/quick-start/)). ## Search does nothing in dev Pagefind's index is built by `astro build`. Use `npm run build && npm run preview` to try search. ## Deploys | Symptom | Cause | |---|---| | "Deploy skipped" notice, build green | No `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID` for this run: fork PR, Dependabot, or secrets not set | | `wrangler missing` error | `wrangler` is not a devDependency of the site; `npm i -D wrangler` and commit the lockfile | | "uploaded but has no preview URL" | `preview_urls` is not `true` in `wrangler.jsonc`, or the account has no workers.dev subdomain | | Authentication or permission error on deploy | Token scope: see [setup for CI](https://astro-project-site.pascaripavel.workers.dev/docs/guides/deploying/#setup-for-ci) (Editor on the Worker; Workers Routes Write for a custom domain) | | `docs-gen: … stale block(s)` | Run `npm run docs:gen` and commit | --- # Options URL: https://astro-project-site.pascaripavel.workers.dev/docs/reference/options/ `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() | 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 `` 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` | `{}` | 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` | | 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` | `{}` | 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 An entry of `externalDocs`. See [Docs: mounting external markdown](https://astro-project-site.pascaripavel.workers.dev/docs/guides/docs/#mount-markdown-from-elsewhere). | 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 An entry of `mirrors`. See [Mirrors](https://astro-project-site.pascaripavel.workers.dev/docs/guides/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 The `landing` option. Every part is optional; a section without content is not rendered. See [Landing page](https://astro-project-site.pascaripavel.workers.dev/docs/guides/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 ``). | | `features` | `SectionContent` | | 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` | | 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 | Field | Type | Required | Description | |---|---|---|---| | `title` | `string` | yes | | | `body` | `string` | yes | | | `href` | `string` | | Makes the whole card a link. | ### Step | 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 Used by `nav`, `hero.primary`/`secondary` and `cta.primary`/`secondary`. | Field | Type | Required | Description | |---|---|---|---| | `label` | `string` | yes | | | `href` | `string` | yes | | ### HeroDemo `landing.hero.demo`: a [``](https://astro-project-site.pascaripavel.workers.dev/docs/reference/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` | | | | `modules` | `string[]` | | | | `base` | `string` | | | | `height` | `number \| string` | | | ## ComponentOverrides The `components` option. Values are paths relative to the project root, or package specifiers. See [Overriding components](https://astro-project-site.pascaripavel.workers.dev/docs/guides/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 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 | | --- # Components URL: https://astro-project-site.pascaripavel.workers.dev/docs/reference/components/ ```astro --- --- ``` Imports from `astro-project-site/components` are always the **built-in** components. The [`components` option](https://astro-project-site.pascaripavel.workers.dev/docs/guides/overriding-components/) changes what the injected pages render (and what `GalleryGrid` uses for cards), not what this module exports, so an override can wrap the original. Each component is shown rendered, with usage, in the guides: [Landing page](https://astro-project-site.pascaripavel.workers.dev/docs/guides/landing-page/), [Gallery](https://astro-project-site.pascaripavel.workers.dev/docs/guides/gallery/), [Live examples](https://astro-project-site.pascaripavel.workers.dev/docs/guides/live-examples/), [Overriding components](https://astro-project-site.pascaripavel.workers.dev/docs/guides/overriding-components/). ## Components ### Live examples #### Live A live example: the code is written once, shown with Expressive Code and executed. Docs: the "Live examples" page of the astro-project-site docs. Expressive Code's <Code>, imported without Starlight's component barrel and its stylesheet (see virtual.mjs). | Prop | Type | Default | Description | |---|---|---|---| | `code` | `string` | | The example's source. Omit it to use the fenced code block written as the component's child (MDX). | | `lang` | `string` | `runner ? 'json' : 'html'` | Language of `code` for highlighting. Default: `html`, or `json` when a `runner` is set. | | `title` | `string` | | Title shown in the code frame (with `code`; for a fenced child use ```html title="…"). | | `caption` | `string` | | Caption under the example. | | `id` | `string` | (computed) | Stable id and anchor (#id). Default: derived from caption or title, else from the source. | | `mode` | `LiveMode` | `'inline'` | `inline` renders into the page; `iframe` renders in an isolated, auto-sized iframe. Default `inline`. | | `preview` | `LivePreviewPosition` | `'above'` | Where the preview sits relative to the code. `side` falls back to stacked on narrow widths. Default `above`. | | `editable` | `boolean` | `false` | Make the code editable; edits re-run the example (debounced) and a Reset button restores it. | | `runner` | `string` | | URL of a module exporting `run(source, mount, ctx)`. Without it the source is HTML and is rendered as-is. | | `options` | `Record` | | Passed to the runner as `ctx.options`. Must be JSON-serialisable. | | `modules` | `string[]` | | Module URLs to load before the example runs (inline: once per page; iframe: in the iframe's head). | | `head` | `string` | | Extra HTML for the iframe's <head> (styles, scripts, import maps). iframe mode only. | | `base` | `string` | | Base URL for relative paths inside the iframe (<base href>). iframe mode only; passed to runners as ctx.base. | | `sandbox` | `string` | (computed) | iframe sandbox tokens. Default `allow-scripts allow-same-origin allow-popups allow-forms allow-modals`. | | `height` | `number \| string` | | Minimum preview height (number = px, or any CSS length). Also the iframe's height before it measures itself. | | `lazy` | `boolean` | `false` | Start only when scrolled near the viewport. | | `debounce` | `number` | `300` | Debounce for re-running edits, in ms. Default 300. | | `class` | `string` | | Extra class on the root element. | ### Page frame and chrome #### BaseLayout Page frame for everything outside the docs: head metadata, the shared header and footer, theme and base styles. The header bar matches Starlight's so moving between the landing page and the docs feels like one site. The docs search (Starlight's Search, whatever it resolved to) is in the header here too, so search is one keystroke away on every page. Use it for a project's own pages too: import { BaseLayout } from 'astro-project-site/components'; | Prop | Type | Default | Description | |---|---|---|---| | `title` | `string` | | | | `description` | `string` | | | | `image` | `string` | | Social image for this page (defaults to the `ogImage` option / `ogImageFor` hook). | | `noindex` | `boolean` | | | | `type` | `'website' \| 'article'` | | Open Graph type (blog posts are `article`). | | `canonical` | `string` | | Canonical URL when it is not this page's own (e.g. a post first published elsewhere). | Slots: `head`, `default`. #### SiteHead <head> contents for pages outside Starlight: title, description, canonical URL, Open Graph and Twitter tags, favicon, theme bootstrapping. The social image comes from the `ogImage` option or the `ogImageFor` hook unless the page passes `image` (docs pages get the same through route-middleware.ts). | Prop | Type | Default | Description | |---|---|---|---| | `title` | `string` | | Page title. The landing page passes nothing and gets "Name — tagline". | | `description` | `string` | `site.tagline` | | | `image` | `string` | (computed) | Social image for this page: overrides the hook. | | `type` | `'website' \| 'article'` | `'website'` | Open Graph type. | | `noindex` | `boolean` | `false` | Ask search engines not to index this page (e.g. 404). | | `canonical` | `string` | | Canonical URL when it is not this page's own (e.g. a blog post first published elsewhere). | Slots: `default`. #### SiteHeader The one site header: landing page, gallery, and (through overrides/Header.astro) every docs page. It renders the contents of the header bar; the bar itself (height, background, stickiness) belongs to the page frame: BaseLayout for site pages, Starlight's PageFrame for docs. | Prop | Type | Default | Description | |---|---|---|---| | `pathname` | `string` | `Astro.url.pathname` | Current path, for the active nav state. Defaults to the request URL. | | `menu` | `boolean` | `true` | Render the small-screen menu. Default true. The docs header turns it off on pages with a sidebar, where the nav is in Starlight's mobile menu instead, so a page never has two menus holding the same links. | Slots: `search`, `theme`, `theme-menu`. #### SiteFooter The shared footer: under the landing page and the gallery (variant `page`), and at the end of every docs page, after Starlight's edit link and pagination (variant `docs`, see overrides/Footer.astro). | Prop | Type | Default | Description | |---|---|---|---| | `variant` | `'page' \| 'docs'` | `'page'` | `page`: full-width band under a page. `docs`: inside the docs content column. | | `navLabel` | `string` | | Accessible name of the footer's nav. Default: the `footerNav` label. Give a second footer on a page its own. | #### ThemeSelect Theme switch for pages outside Starlight (landing, gallery). It shares Starlight's storage key and `data-theme` attribute, so a choice made here carries over to the docs and back. | Prop | Type | Default | Description | |---|---|---|---| | `id` | `string` | `'site-theme'` | Unique id; needed when the select is rendered more than once on a page. | ### Landing page sections #### Landing The built-in landing page body, composed from the section components and the `landing` option. To change the layout, set `components.Landing` to your own component (it renders inside BaseLayout), or set `landing: false` and write src/pages/index.astro. The section components are exported from 'astro-project-site/components'. No props. #### Hero The top of the landing page: heading, lead paragraph, actions, install command, and a full-bleed `live` slot for anything interactive (a demo canvas, a custom element, a stage of characters). | Prop | Type | Default | Description | |---|---|---|---| | `title` (required) | `string` | | | | `lead` | `string` | | | | `primary` | `LinkAction` | | | | `secondary` | `LinkAction` | | | | `install` | `string` | | | | `headingLevel` | `1 \| 2` | `1` | Level of the title heading: 1 on a landing page (default); 2 when the hero is shown inside another page. | Slots: `default`, `live`. #### Section A landing-page section: optional heading and intro, then whatever you put inside. Sections are plain, stable block boxes (no transforms, no overflow clipping) so live content such as characters walking on the page can measure and stand on them. | Prop | Type | Default | Description | |---|---|---|---| | `id` | `string` | | | | `title` | `string` | | | | `intro` | `string` | | | | `tone` | `'plain' \| 'surface'` | `'plain'` | Tinted background band. | | `class` | `string` | | | Slots: `header`, `default`. #### Features A grid of feature cards. Each card is an <article> with a stable box; linked cards have a real link on the title (the whole card is clickable via a stretched hit area, not a wrapper link). | Prop | Type | Default | Description | |---|---|---|---| | `items` (required) | `Feature[]` | | | #### Steps Numbered "how it works" steps, each with an optional code sample highlighted at build time. | Prop | Type | Default | Description | |---|---|---|---| | `items` (required) | `Step[]` | | | #### GalleryStrip The landing page's gallery section: the first few gallery items and a link to the rest. | Prop | Type | Default | Description | |---|---|---|---| | `title` | `string` | `t('gallery')` | | | `intro` | `string` | | | | `limit` | `number` | `3` | | | `kinds` | `string[]` | | Only items of these kinds. | #### CallToAction The closing call to action. | Prop | Type | Default | Description | |---|---|---|---| | `title` (required) | `string` | | | | `body` | `string` | | | | `primary` | `LinkAction` | | | | `secondary` | `LinkAction` | | | Slots: `default`. #### InstallCommand A shell command with a copy button. The button appears only when the Clipboard API is available. | Prop | Type | Default | Description | |---|---|---|---| | `command` (required) | `string` | | | | `label` | `string` | `t('installCommand')` | Accessible name for the command, read before it. | ### Docs #### ChildCards A grid of cards for the pages and subfolders of a docs folder: title, description, and for a folder the number of pages in it. Folders without an index page get such a page automatically; put `` in a folder's own index page to show the same grid there, or pass `dir` to list any folder. On a docs page the cards follow the sidebar order; elsewhere `sidebar.order`, then title. | Prop | Type | Default | Description | |---|---|---|---| | `dir` | `string` | | Folder to list, as a collection id (`docs/guides`) or path (`/docs/guides/`). Default: the current docs page. | | `exclude` | `string[]` | | Collection ids or paths to leave out. | | `label` | `string` | | Accessible name of the list. | ### Gallery #### GalleryPage The built-in /gallery/ page body: every published item, with kind and tag filters. Without JavaScript all items are shown; with it, the filters appear (and are reflected in the URL: ?kind=demo&tag=canvas). Replace it with `components.Gallery` (same props; it renders inside BaseLayout). | Prop | Type | Default | Description | |---|---|---|---| | `items` (required) | `GalleryEntry[]` | | | | `title` (required) | `string` | | | | `description` (required) | `string` | | | #### GalleryGrid A responsive grid of gallery cards. Used by /gallery/ and by the landing page's gallery strip. Cards are the built-in GalleryCard, or the project's `components.GalleryCard`. | Prop | Type | Default | Description | |---|---|---|---| | `items` (required) | `GalleryEntry[]` | | | | `headingLevel` | `2 \| 3 \| 4` | `3` | | | `minWidth` | `string` | `'16rem'` | Minimum card width before the grid wraps. | | `id` | `string` | | | #### GalleryCard One gallery item: poster, kind, title (the link), description, tags. The card is a plain <article>; the whole card is clickable through a stretched hit area on the title link. | Prop | Type | Default | Description | |---|---|---|---| | `item` (required) | `GalleryEntry` | | | | `headingLevel` | `2 \| 3 \| 4` | `3` | Heading level for the title, to fit the page outline. | #### GalleryFilters Kind and tag filters for a GalleryGrid. Hidden until its script runs, so without JavaScript the page simply shows every item. The current filter is mirrored in the URL (?kind=…&tag=…) so it can be shared. | Prop | Type | Default | Description | |---|---|---|---| | `kinds` (required) | `string[]` | | | | `tags` (required) | `string[]` | | | | `target` (required) | `string` | | id of the GalleryGrid to filter. | | `total` (required) | `number` | | | ### Blog #### BlogIndex The post list body: /blog/, /blog/2/, ... and each tag page /blog/tags/<tag>/. Renders inside BaseLayout. Replace it with `components.BlogIndex` (props: BlogIndexProps). | Prop | Type | Default | Description | |---|---|---|---| | `posts` (required) | `BlogEntry[]` | | The posts on this page, newest first. | | `title` (required) | `string` | | | | `description` (required) | `string` | | | | `tag` | `object` | | Set on tag pages. | | `tag.tag` (required) | `string` | | | | `tag.slug` (required) | `string` | | | | `tag.count` (required) | `number` | | | | `tags` (required) | `{ tag: string; slug: string; count: number }[]` | | Every tag, most used first. | | `page` (required) | `object` | | Pagination (1-based). Tag pages are a single page. | | `page.current` (required) | `number` | | | | `page.last` (required) | `number` | | | | `page.total` (required) | `number` | | | | `page.prev` | `string` | | | | `page.next` | `string` | | | #### BlogPost One post's page body (inside BaseLayout): title, dates, authors, reading time, the post itself in a reading column with room for margin notes, tags, an "Edit this post" link and the newer/older posts. Replace it with `components.BlogPost` (props: BlogPostProps; the rendered post is the default slot). | Prop | Type | Default | Description | |---|---|---|---| | `post` (required) | `BlogEntry` | | | | `readingTime` (required) | `number` | | | | `authors` (required) | `BlogAuthor[]` | | | | `editUrl` | `string` | | "Edit this post" link, when the repository layout is known. | | `newer` | `BlogEntry` | | | | `older` | `BlogEntry` | | | Slots: `default`. #### BlogCard One post in a list: the blog index, tag pages and the landing page's "Latest posts". Replace it with `components.BlogCard` (props: `post`, `headingLevel`, `variant`). | Prop | Type | Default | Description | |---|---|---|---| | `post` (required) | `BlogEntry` | | | | `headingLevel` | `2 \| 3 \| 4` | `2` | Heading level for the title, to fit the page outline. | | `variant` | `'row' \| 'tile'` | `'row'` | `row`: a full-width entry with the image beside the text (the post list). `tile`: a card for grids. | #### BlogTags The tag index body (/blog/tags/): every tag with its post count. Renders inside BaseLayout. | Prop | Type | Default | Description | |---|---|---|---| | `tags` (required) | `{ tag: string; slug: string; count: number }[]` | | | | `title` (required) | `string` | | | #### PostMeta The line under a post's title (and in lists): date, "updated" date, reading time, authors, and a Draft badge in dev. | Prop | Type | Default | Description | |---|---|---|---| | `post` (required) | `BlogEntry` | | | | `readingTime` (required) | `number` | | | | `authors` | `BlogAuthor[]` | `[]` | Shown when given (the post page passes them; lists leave them out). | | `class` | `string` | | | #### TagList A post's tags, each a link to its tag page. | Prop | Type | Default | Description | |---|---|---|---| | `tags` (required) | `string[]` | | | | `label` | `string` | | Visible label before the list ("Tagged"); the list is labelled "Tags" either way. | | `class` | `string` | | | #### LatestPosts "Latest posts": the newest few posts and a link to the rest. The built-in landing page shows it when the blog is on (option `blog.landing`); a custom landing can use it too: import { LatestPosts } from 'astro-project-site/components'; <LatestPosts limit={3} /> | Prop | Type | Default | Description | |---|---|---|---| | `title` | `string` | `t('latestPosts')` | | | `intro` | `string` | | | | `limit` | `number` | `3` | How many posts. Default 3. | | `tone` | `'plain' \| 'surface'` | `'plain'` | Section background. | ### Writing: side notes for posts and docs pages #### MarginNote A side note anchored to a spot in the text. | Prop | Type | Default | Description | |---|---|---|---| | `kind` | `'note' \| 'field' \| 'warning'` | `'note'` | `note` (default), `field` (a field note: an observation from practice), or `warning`. | | `label` | `string` | | Label above the note. Default: the `note`, `fieldNote` or `warning` label; `''` for none. | | `numbered` | `boolean` | `false` | Number the note and put the number in the text at the anchor (numbers count up through the page). | | `id` | `string` | | | Slots: `default`. ### Helpers - `galleryItems` - `distinct` - `blogPosts` - `postInfo` - `readingTime` - `tagSlug` - `formatDate` - `activeHref` - `isActive` - `isExternal` `galleryItems()` returns the published gallery entries sorted by `order`, then title. `distinct(items, pick)` returns the distinct values `pick` returns across items, in first-seen order. `isActive(href, pathname)` is true when the page is in a nav link's section; `activeHref(hrefs, pathname)` picks the one link to mark as current (the most specific of those, so `/docs/guide/` wins over `/docs/` on a guide page); `isExternal(href)` is true for `scheme://` URLs. --- # Live and runners URL: https://astro-project-site.pascaripavel.workers.dev/docs/reference/live/ How-to with running examples: [Live examples](https://astro-project-site.pascaripavel.workers.dev/docs/guides/live-examples/). ## Live props Defaults come from `Live.astro`. | Field | Type | Default | Required | Description | |---|---|---|---|---| | `code` | `string` | | | The example's source. Omit it to use the fenced code block written as the component's child (MDX). | | `lang` | `string` | `runner ? 'json' : 'html'` | | Language of `code` for highlighting. Default: `html`, or `json` when a `runner` is set. | | `title` | `string` | | | Title shown in the code frame (with `code`; for a fenced child use ```html title="…"). | | `caption` | `string` | | | Caption under the example. | | `id` | `string` | (computed) | | Stable id and anchor (#id). Default: derived from caption or title, else from the source. | | `mode` | `LiveMode` | `'inline'` | | `inline` renders into the page; `iframe` renders in an isolated, auto-sized iframe. Default `inline`. | | `preview` | `LivePreviewPosition` | `'above'` | | Where the preview sits relative to the code. `side` falls back to stacked on narrow widths. Default `above`. | | `editable` | `boolean` | `false` | | Make the code editable; edits re-run the example (debounced) and a Reset button restores it. | | `runner` | `string` | | | URL of a module exporting `run(source, mount, ctx)`. Without it the source is HTML and is rendered as-is. | | `options` | `Record` | | | Passed to the runner as `ctx.options`. Must be JSON-serialisable. | | `modules` | `string[]` | | | Module URLs to load before the example runs (inline: once per page; iframe: in the iframe's head). | | `head` | `string` | | | Extra HTML for the iframe's <head> (styles, scripts, import maps). iframe mode only. | | `base` | `string` | | | Base URL for relative paths inside the iframe (<base href>). iframe mode only; passed to runners as ctx.base. | | `sandbox` | `string` | (computed) | | iframe sandbox tokens. Default `allow-scripts allow-same-origin allow-popups allow-forms allow-modals`. | | `height` | `number \| string` | | | Minimum preview height (number = px, or any CSS length). Also the iframe's height before it measures itself. | | `lazy` | `boolean` | `false` | | Start only when scrolled near the viewport. | | `debounce` | `number` | `300` | | Debounce for re-running edits, in ms. Default 300. | | `class` | `string` | | | Extra class on the root element. | Either `code` or a fenced code block as the only child (MDX, with blank lines around it) is required; without either the build fails with "`` needs its code". ## Runner modules A runner is a plain ES module served as a static file (from `public/` or a [mirror](https://astro-project-site.pascaripavel.workers.dev/docs/guides/mirrors/)), not bundled by Astro. It exports one function: ```ts export type LiveRunner = (source: string, mount: HTMLElement, ctx: LiveContext) => LiveRunResult; export type LiveRunResult = void | (() => void) | Promise void)>; ``` - `source` is the code as shown, or as the reader edited it. - `mount` is an empty element. In inline mode it is a fresh `div` in the page; in iframe mode a `div` in the iframe's `#live-root`. - Throw (or reject) to show the error under the preview. The previous good render stays on screen. - Return a cleanup function (or a promise of one). It runs before the next run and when the example is removed. - The module must export `run`; otherwise the example shows "… does not export run(source, mount, ctx)". - It is loaded once per page (inline) or once per iframe. In iframe mode later runs reuse the loaded module. ### When a runner re-runs - after an edit (debounced by `debounce`) or Reset; - when the page theme changes (`ctx.theme`); - when `prefers-reduced-motion` changes (`ctx.reducedMotion`); - when the element is moved in the DOM. The previous run's `ctx.signal` is aborted and its cleanup called first. ## LiveContext | Field | Type | Required | Description | |---|---|---|---| | `id` | `string` | yes | The example's id (also its anchor on the page). | | `mode` | `LiveMode` | yes | Where the example renders: in the page, or inside its own iframe. | | `options` | `Record` | yes | The `options` prop, as given (JSON-serialisable). | | `reducedMotion` | `boolean` | yes | `prefers-reduced-motion: reduce` at the time of this run. The example re-runs when it changes. | | `theme` | `'light' \| 'dark'` | yes | The page theme, from Starlight's `data-theme` (or the OS preference outside Starlight). | | `base` | `string` | yes | Base URL relative paths should resolve against (the `base` prop, else the page URL). | | `signal` | `AbortSignal` | yes | Aborted when this run is replaced (edit, reset, theme or motion change) or the example is removed. | | `status()` | `(message: string, level?: LiveStatusLevel) => void` | yes | Show a one-line status under the preview (`error` is styled as an error but does not throw). | `LiveStatusLevel` is `'ok' | 'info' | 'warn' | 'error'`. A status set from an outdated run is ignored. Types: `import type { LiveRunner, LiveContext } from 'astro-project-site'` (also exported from `astro-project-site/components`). In a plain `.js` runner use JSDoc: ```js /** @type {import('astro-project-site').LiveRunner} */ export const run = (source, mount, ctx) => { /* … */ }; ``` --- # Content collections URL: https://astro-project-site.pascaripavel.workers.dev/docs/reference/content/ ```ts title="src/content.config.ts" export const collections = projectSiteCollections(); ``` `projectSiteCollections(options?)` returns three collections: | Collection | Loader | Schema | |---|---|---| | `docs` | Starlight's `src/content/docs/` loader, plus one `glob()` per `externalDocs` folder (`.md` only), plus a default `404` entry when you have none | Starlight's `docsSchema()`, extended with `docsExtend` | | `gallery` | `glob('**/*.{md,yaml,yml,json}')` in `galleryBase` | `gallerySchema` (below) | | `i18n` | Starlight's `i18nLoader()` when `src/content/i18n/` exists; otherwise one empty `en` entry, so Astro does not warn | Starlight's `i18nSchema()` | | Option | Type | Default | Description | |---|---|---|---| | `docsExtend` | zod object | | Extra frontmatter fields for docs pages (Starlight's `docsSchema({ extend })`). | | `galleryBase` | `string` | `'./src/content/gallery'` | Folder of gallery items, relative to the project root. | The package also exports `gallerySchema` and `projectDocsLoader()` for a hand-written content config. ```ts title="src/content.config.ts: adding a docs field" export const collections = projectSiteCollections({ docsExtend: z.object({ since: z.string().optional() }), }); ``` ## Gallery item One file per item in `src/content/gallery/` (YAML, JSON, or Markdown frontmatter). From `gallerySchema` in `src/content.ts`: | Field | Type | Default | Required | Description | |---|---|---|---|---| | `title` | `string` | | yes | | | `description` | `string` | | yes | | | `href` | `string` | | yes | Where the card links: a site path (`/apps/hello/`) or a full URL. | | `kind` | `string` | `'example'` | | Free-form category used by the filter, e.g. `demo`, `example`, `tool`, `character`. | | `poster` | `image (local file)` | | | Poster image next to the entry file, optimised at build time (e.g. `./hello.png`). | | `posterUrl` | `string` | | | Poster served as-is: a path under public/ or a mirrored app (`/apps/x/poster.png`), or a full URL. | | `posterAlt` | `string` | `''` | | Alt text for the poster. Empty (the default) marks it decorative, since the title already names it. | | `pixelated` | `boolean` | `false` | | Render the poster with crisp, unsmoothed pixels (pixel art, small sprites). | | `tags` | `string[]` | `[]` | | | | `order` | `number` | `100` | | Sort key, ascending; ties sort by title. | | `external` | `boolean` | `false` | | Link leaves the site (a different origin or an app outside the build). Adds an indicator. | | `draft` | `boolean` | `false` | | Hide the item without deleting it. | `poster` is resolved relative to the entry file and optimised at build time; `posterUrl` is used as it is. See [Gallery](https://astro-project-site.pascaripavel.workers.dev/docs/guides/gallery/). ## Docs frontmatter Local pages use [Starlight's frontmatter](https://starlight.astro.build/reference/frontmatter/). Two fields matter to the generated sidebar of top-level pages in `src/content/docs/docs/`: `sidebar.order` (ascending; the index page always comes first) and `sidebar.hidden: true`. Mounted markdown files need no frontmatter. When they have none, they get: | Field | Value | |---|---| | `title` | The first `# H1` (removed from the body), else the file name | | `description` | The first paragraph before any heading, cut to one sentence (≤ 200 characters) | | `editUrl` | `/edit//`, or `false` outside the repo | | `slug` | Always set from the file's path (it is what the links validator keys pages by) | Frontmatter you write wins for `title`, `description` and `editUrl`. An H1 is also removed when the file starts with it, even if the frontmatter has a title. --- # CLI URL: https://astro-project-site.pascaripavel.workers.dev/docs/reference/cli/ The package's only bin is `project-site`. In a project it is on the npm scripts' `PATH`; elsewhere run it with `npx astro-project-site ` (npx picks the package's single bin). ```text Usage: project-site [options] Commands: init [dir] Create a project site in dir (default: .) from the repository it is for: landing page from the README, its markdown as docs, demo pages in a gallery, a blog with a draft post --from Repository to read (default: dir's parent inside a git repo, else the current folder) --yes, -y Write without asking (needed when not run in a terminal) --dry-run Print what was found and what would be written; write nothing --force Overwrite files that already exist --blank Copy the plain starter instead (placeholders and example docs, no detection) --ci Also write .github/workflows/site.yml: checks and a preview per pull request, production deploys on v* tags (needs Cloudflare secrets). Without it, deploy with npm run deploy --name Project name shown on the site (default: README title, manifest or folder name) --package Version spec for the astro-project-site dependency (default: ^) docs:gen Fill blocks in markdown (reads ./docs-gen.config.mjs) --check Change nothing; exit 1 with a diff when a block is stale --config Another config file docs:check Same as docs:gen --check deploy:preview Upload dist/ to Cloudflare as a preview version (uses the project's wrangler) --alias Preview alias (default: the git branch) --message Version message --dry-run Validate without uploading ``` ## init Copies the starter into `dir` (default `.`) and names it: - `package.json` → `name` is the slug of `--name` or the folder; the `astro-project-site` dependency becomes `--package` (default `^`). - `wrangler.jsonc` → the first `"name"` becomes the slug. - `astro.config.mjs` → `name: '…'` becomes `--name` or the folder name in title case (`my-lib` → "My Lib"). - `.github/workflows/site.yml`, only with `--ci` → the reusable workflow is pinned to `@v`. - `_gitignore` is written as `.gitignore`. `node_modules`, `dist`, `.astro`, `.wrangler` and `package-lock.json` are never copied. If any starter file already exists in the target, it lists them and writes nothing (exit 1) unless you pass `--force`, which overwrites them. Other files in the folder are left alone. ## docs:gen and docs:check Reads `docs-gen.config.mjs` from the current folder (or `--config`), fills every `` … `` block. `docs:check` (= `docs:gen --check`) writes nothing and exits 1 with a diff when a block is stale. Errors (exit 1): an unknown generator, an unclosed or nested block, a generator that throws or returns a non-string, a listed path that does not exist. See [Docs generation](https://astro-project-site.pascaripavel.workers.dev/docs/guides/docs-generation/). ## deploy:preview Run from the project root after `npm run build`. It: 1. reads the Worker name from `wrangler.jsonc` (or `wrangler.json`); 2. makes the alias from `--alias`, else `$PREVIEW_ALIAS`, else the current git branch: lowercased, non `[a-z0-9]` runs become `-`, prefixed with `b-` if it does not start with a letter, cut so that `-` fits in 63 characters; 3. runs the **project's own** wrangler (`node_modules/wrangler`; it fails if there is none, it never downloads one): `wrangler versions upload --preview-alias [--message …] [--dry-run] [extra args]`; 4. prints the alias URL and, inside GitHub Actions, writes `url`, `alias`, `version_url`, `version_id` to `$GITHUB_OUTPUT`. It fails when `dist/` is missing, or when the upload has no preview URL (`preview_urls` off, or no workers.dev subdomain). Arguments after `--` go to wrangler. --- # Theme tokens URL: https://astro-project-site.pascaripavel.workers.dev/docs/reference/theme-tokens/ From `astro-project-site/theme.css`, which every page loads. Override brand tokens in a [`customCss`](https://astro-project-site.pascaripavel.workers.dev/docs/guides/theming/) file; Starlight's `--sl-color-*` palette, fonts and nav height are mapped from them, so the docs follow. **Brand tokens** (override these): | Token | Dark (default) | Light | |---|---|---| **Derived tokens** (computed from the brand tokens; usually leave alone): | Token | Value | Light | |---|---|---| | `--site-accent` | `#8b9cff` | `#3b4fd8` | | `--site-bg` | `#111318` | `#ffffff` | | `--site-surface` | `#1a1d24` | `#f6f7f9` | | `--site-text` | `#e8e9ee` | `#1b1d23` | | `--site-muted` | `#a0a4b0` | `#5b6070` | | `--site-border` | `#2b2f3a` | `#dfe2e8` | | `--site-code-bg` | `#0b0d11` | `#1b1d23` | | `--site-code-text` | `#e8e9ee` | `#e8e9ee` | | `--site-font-body` | `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', 'Noto Sans', Arial, sans-serif` | same | | `--site-font-heading` | `var(--site-font-body)` | same | | `--site-font-mono` | `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace` | same | | `--site-radius` | `0.75rem` | same | | `--site-space` | `1rem` | same | | `--site-max-width` | `72rem` | same | | `--site-header-height` | `3.5rem` | same | | `--site-accent-soft` | `color-mix(in oklab, var(--site-accent) 16%, var(--site-bg))` | same | | `--site-accent-strong` | `color-mix(in oklab, var(--site-accent) 70%, var(--site-text))` | same | | `--site-on-accent` | `var(--site-bg)` | same | | `--site-link` | `var(--site-accent-strong)` | same | | `--site-focus` | `var(--site-accent)` | same | | `--site-radius-sm` | `calc(var(--site-radius) / 2)` | same | | `--site-shadow` | `0 1px 2px rgb(0 0 0 / 0.12), 0 4px 12px rgb(0 0 0 / 0.08)` | same | The `theme` option's `accent` / `accentDark` set `--site-accent` for the light / dark theme with a more specific selector (`html:root…`), so they win over a `customCss` value for that one token. --- # Exports and virtual modules URL: https://astro-project-site.pascaripavel.workers.dev/docs/reference/exports/ | Import | What | |---|---| | `astro-project-site` | `default projectSite(options)`, `mirror(entries)` (the mirror integration on its own); types | | `astro-project-site/components` | The components and helpers listed under [Components](https://astro-project-site.pascaripavel.workers.dev/docs/reference/components/) | | `astro-project-site/content` | `projectSiteCollections()`, `gallerySchema`, `projectDocsLoader` ([Content collections](https://astro-project-site.pascaripavel.workers.dev/docs/reference/content/)) | | `astro-project-site/config` | The validated options plus `version`, for your own pages | | `astro-project-site/theme.css` | The design tokens. Loaded on every page already; import it only in a page that uses neither `BaseLayout` nor Starlight | | `astro-project-site/virtual` | Types only: the declarations below | Types exported from `astro-project-site`: `ProjectSiteOptions`, `ResolvedOptions`, `ResolvedLanding`, `SiteConfig`, `LandingContent`, `HeroDemo`, `Feature`, `Step`, `SectionContent`, `LinkAction`, `ExternalDocs`, `Mirror`, `ComponentOverrides`, `GalleryEntry`, `GalleryData`, `OgImageHook`, `OgImageRequest`, and the [Live types](https://astro-project-site.pascaripavel.workers.dev/docs/reference/live/) `LiveProps`, `LiveRunner`, `LiveContext`, `LiveRunResult`, `LiveMode`, `LivePreviewPosition`, `LiveStatusLevel`. ## astro-project-site/config ```astro title="src/pages/about.astro" --- ---

    {config.name} v{config.version}: {config.tagline}

    ``` The default export is `SiteConfig`: the options after validation and defaults (`nav` filled in, `url` and `repo` without trailing slash, `features`/`steps` normalised to `{ title, intro, items }`), **minus** `components`, `starlight`, `customCss`, `ogImageFor` and `mirrors`, **plus** `version` (read from `versionFrom` at startup). ## Virtual modules `astro-project-site/config` re-exports `virtual:astro-project-site/config`. The integration serves five virtual modules and injects their types into `.astro/`, so `astro check` passes without setup. Only `config` is meant for projects; the others are how the built-in components find overrides and may change between minor versions. ```ts title="src/virtual.d.ts" // Types for the virtual modules served by astro-project-site. projectSite() injects this file into the project's // .astro/ types, so `astro check` knows them in any project that uses the integration. declare module 'virtual:astro-project-site/config' { const config: import('astro-project-site').SiteConfig; export default config; } declare module 'virtual:astro-project-site/components' { type Component = import('astro/runtime/server/index.js').AstroComponentFactory; export const Header: Component; export const Footer: Component; export const Hero: Component; export const Landing: Component; export const GalleryCard: Component; export const Gallery: Component; export const BlogIndex: Component; export const BlogPost: Component; export const BlogCard: Component; } declare module 'virtual:astro-project-site/og' { const ogImageFor: import('astro-project-site').OgImageHook; export default ogImageFor; } declare module 'virtual:astro-project-site/user-css' {} declare module 'virtual:astro-project-site/starlight' { type Component = import('astro/runtime/server/index.js').AstroComponentFactory; export const Search: Component; export const ThemeSelect: Component; export const showSearch: boolean; } declare module 'virtual:astro-project-site/code' { export const Code: typeof import('@astrojs/starlight/components').Code; } declare module 'virtual:astro-project-site/components/Header' { const component: import('astro/runtime/server/index.js').AstroComponentFactory; export default component; } declare module 'virtual:astro-project-site/components/Footer' { const component: import('astro/runtime/server/index.js').AstroComponentFactory; export default component; } declare module 'virtual:astro-project-site/components/Hero' { const component: import('astro/runtime/server/index.js').AstroComponentFactory; export default component; } declare module 'virtual:astro-project-site/components/Landing' { const component: import('astro/runtime/server/index.js').AstroComponentFactory; export default component; } declare module 'virtual:astro-project-site/components/GalleryCard' { const component: import('astro/runtime/server/index.js').AstroComponentFactory; export default component; } declare module 'virtual:astro-project-site/components/Gallery' { const component: import('astro/runtime/server/index.js').AstroComponentFactory; export default component; } declare module 'virtual:astro-project-site/components/BlogIndex' { const component: import('astro/runtime/server/index.js').AstroComponentFactory; export default component; } declare module 'virtual:astro-project-site/components/BlogPost' { const component: import('astro/runtime/server/index.js').AstroComponentFactory; export default component; } declare module 'virtual:astro-project-site/components/BlogCard' { const component: import('astro/runtime/server/index.js').AstroComponentFactory; export default component; } ``` --- # How the docs mount works URL: https://astro-project-site.pascaripavel.workers.dev/blog/2026/how-the-docs-mount-works/ Published: 2026-11-18 The promise of `externalDocs` is that the docs a project already has, a folder of plain markdown next to the code, become part of the site as they are. No frontmatter, no copying, no second source of truth. This post follows one file through the pipeline to show what that takes. ```js title="astro.config.mjs" projectSite({ // ... externalDocs: [{ dir: '../docs', route: 'reference', label: 'Reference', order: ['getting-started.md'] }], }); ``` ## One collection, several loaders Starlight renders whatever is in the `docs` content collection. Normally that collection has one loader, reading `src/content/docs/`. The mount gives it more: `projectDocsLoader()` runs Starlight's own loader for the local pages, then one Astro `glob()` loader per `externalDocs` entry, each with `**/*.md` as its pattern and the entry's `exclude` globs subtracted. There is a catch. A content loader cleans up after itself: any entry in the store that it did not see on this run is deleted, on the assumption that its file was removed. With several loaders sharing one store, each would delete the others' pages.Without the filter, whichever loader ran last would decide which pages exist: the local pages or one mounted folder, never all of them. So each loader gets a view of the store whose `keys()` only lists entries from its own folder. The store itself is shared; the view is a `Proxy` that filters one method. ## What happens to a file Take `docs/getting-started.md`, mounted with `route: 'reference'`. On its way into the collection: 1. **It gets an id from its path.** `getting-started.md` becomes `docs/reference/getting-started`, and so the URL `/docs/reference/getting-started/`. A `README.md` or `index.md` takes its folder's id, the way GitHub shows a folder's README. 2. **It gets a title from its first heading.** Files written for GitHub start with `# Getting started`, not with frontmatter. The first H1 outside a code block becomes the title and is removed from the body, so it is not shown twice.When the file does have frontmatter with a title, the H1 is only removed if it is the first thing in the body. 3. **It gets a description** from the first sentence of its first paragraph, for search results and link previews. 4. **Its links are rewritten.** This is the part that makes a GitHub folder work as a website, and it has its own section below. 5. **It gets an edit link** to the file in the repository, not to where it would be in `src/content/docs/`. ## Links A link in a markdown file on GitHub is relative to the file: `[API](api.md#exports)`, `[the source](../src/index.js)`. On the site those would point at nothing. Every relative link is resolved against the file it is written in, and then: - if the target is a `.md` file inside any mounted folder, the link becomes that page's URL: `/docs/reference/api/#exports`. An anchor that points at the target's own H1 is dropped, since that heading is now the page title; - if the target is a folder with a `README.md`, it links to that page; - anything else inside the repository (source files, folders, docs that are not mounted) links to the file on GitHub, `/blob//...` or `tree` for a folder; - absolute URLs, root-relative paths, pure `#anchors`, images and anything inside code are left alone. | Written in docs/guides/deploy.md | Becomes | |---|---| | `../api.md#exports` | `/docs/reference/api/#exports` | | `./` (a folder with a README) | `/docs/reference/guides/` | | `../../src/index.js` | `https://github.com/me/lib/blob/main/src/index.js` | | `https://example.com` | unchanged | After that, [starlight-links-validator](https://github.com/HiDeoo/starlight-links-validator) checks every internal link and anchor, and the build fails on a broken one.The validator only knows docs pages. The landing page, the gallery, the blog, `llms.txt` and mirrored folders are added to its list of known paths, so linking to them from a docs page is fine. A link to a `.md` file that does not exist is still rewritten to the URL it would have had, precisely so the validator reports it. ## Edit links need the git root "Edit this page" should open the file on GitHub. That needs the file's path from the root of the repository, which is not the project root when the site lives in a `site/` folder of a monorepo, and the docs in `../docs`. The integration walks up from the project root until it finds `.git` and computes every path from there. Right after `project-site init` there is no `.git` yet. In that case the project root is assumed to become the repository root, which is what a fresh project usually turns into. ## The sidebar comes from the folder Starlight's sidebar is generated from the same folders: local pages first (by `sidebar.order`, then name), one group per mount, each subfolder a collapsed group titled by its README's heading. Within a mount, the README leads, then the files listed in `order`, then the rest by name. The sidebar is built from the file system when the dev server starts. Editing a page reloads it; adding or removing a page needs a restart to show up in the sidebar.Starlight's sidebar is part of its configuration, which is read once. The content collection is live; the config is not. ## The same order everywhere `/llms.txt` lists the docs grouped and ordered like the sidebar: local pages, then one section per mount. `/llms-full.txt` is every page as markdown, in that order, with root-relative links made absolute so they work outside the site. This blog's posts follow, after the docs. None of this is visible when it works, which is the point: you write markdown for GitHub, and the site keeps up. --- # Introducing astro-project-site URL: https://astro-project-site.pascaripavel.workers.dev/blog/2026/introducing-astro-project-site/ Published: 2026-11-10 Every open-source project ends up needing the same website. A front page that says what the thing is and how to install it. Docs that stay in step with the code. A few examples that actually run. Somewhere to say what changed. And every project builds that website from scratch, usually on a weekend, usually twice. astro-project-site is that website as one Astro integration. You add `projectSite({ name, tagline, url, repo })` to `astro.config.mjs` and get a landing page, [Starlight](https://starlight.astro.build) docs, a gallery, `llms.txt`, this blog, and a shared header and footer that make all of it feel like one site. ## The docs live where the code lives Most projects already have documentation: a `docs/` folder of plain markdown, written for GitHub, linked with relative `.md` links. The usual advice is to move it into the site's content folder and add frontmatter to every file. That splits the docs from the code, and the copy in the repo quietly goes stale. Here the folder stays where it is. `externalDocs` mounts it under `/docs//`: titles come from each file's first heading, links are rewritten for the site, and the sidebar is generated from the folder.The [deployed starter](https://project-site-starter.pascaripavel.workers.dev/docs/reference/) mounts its example folder under /docs/reference/. Those files have no frontmatter at all; open one on GitHub and on the site side by side. The next post goes through [how the mount works](https://astro-project-site.pascaripavel.workers.dev/blog/2026/how-the-docs-mount-works/), line by line. ## Examples that run A code sample that has never been executed is a guess. `` takes one piece of code and shows it twice: as a highlighted code block, and running. The component reads the source back from the rendered block, so what runs is exactly what is shown. Edit this one: ```html title="pill.html" ``` It works in docs pages, on the landing page and, as you can see, in blog posts.Inline mode runs the code in the page; `mode="iframe"` gives it a document of its own, and a `runner` module can execute anything else (JSON configs, a DSL, a canvas sketch). ## One theme, everywhere Starlight has its own design system, and project sites usually bolt a landing page onto it that looks almost, but not quite, the same. Here every colour derives from a handful of `--site-*` tokens: the landing page, the gallery, this blog and Starlight's `--sl-*` palette all read them. Change `--site-accent` and the whole site follows, in light and dark. | Part | What you write | What you get | |---|---|---| | Landing | the `landing` option, or your own page | hero, features, steps, gallery strip, latest posts | | Docs | a markdown folder, anywhere in the repo | Starlight pages, sidebar, search, edit links | | Gallery | one YAML or Markdown file per item | a filterable grid of demos | | Blog | Markdown or MDX in `src/content/blog/` | list, tags, RSS, `llms.txt` | ## What you don't have to build - **Deploys.** The starter deploys to Cloudflare Workers with a preview per pull request, from one reusable workflow. - **Static apps.** `mirrors` copies folders of HTML and JavaScript into the build byte for byte, so demos that were never meant to be bundled keep working. - **Machine-readable docs.** `/llms.txt` and `/llms-full.txt` are generated from the same pages. - **A broken-link check.** The build fails on a dead internal link in the docs. ## Start ```bash npx astro-project-site@beta init my-site cd my-site && npm install && npm run dev ``` The [quick start](https://astro-project-site.pascaripavel.workers.dev/docs/quick-start/) takes it from there. If you already have a repository with a `docs/` folder, [add a site to an existing repo](https://astro-project-site.pascaripavel.workers.dev/docs/existing-repo/) instead.