Skip to content

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

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

landing.hero.demo takes the <Live> props (except id, head, sandbox, lazy, debounce, class) and renders the example under the hero copy. The demo code is a string:

demo: {
code: `<script type="module" src="/apps/live-assets/hello-badge.js"></script>
<hello-badge name="world"></hello-badge>`,
title: 'hello.html',
mode: 'iframe',
editable: true,
},

For a JSON spec run by your library, set runner (see custom runners).

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.

My Lib

Parses things, quickly. No dependencies.

npm i my-lib

Optional content under the actions.

<status-pill label="hero slot"></status-pill>
src/pages/example.astro
<Hero
title="My Lib"
lead="Parses things, quickly. No dependencies."
primary={{ label: 'Get started', href: '/docs/quick-start/' }}
secondary={{ label: 'Reference', href: '/docs/reference/' }}
install="npm i my-lib"
>
<p>Optional content under the actions.</p>
<div slot="live">
<Live code={'<status-pill label="hero slot"></status-pill>'} modules={['/docs-assets/status-pill.js']} />
</div>
</Hero>

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.

Why it exists

The short version.

  • Small

    One module you can read in an afternoon.

  • Typed

    Ships its own TypeScript types.

  • Portable

    Plain HTML, any bundler, or none.

src/pages/example.astro
<Section title="Why it exists" intro="The short version." tone="surface">
<Features items={[
{ title: 'Small', body: 'One module you can read in an afternoon.' },
{ title: 'Typed', body: 'Ships its own TypeScript types.', href: '/docs/reference/' },
{ title: 'Portable', body: 'Plain HTML, any bundler, or none.' },
]} />
</Section>

A feature with href gets a real link on its title, and the whole card is clickable. tone="surface" tints the section band.

  1. Install

    Add the package.

    npm i my-lib
  2. Call it

    One function.

    parse('1 + 2'); // 3
src/pages/example.astro
<Steps items={[
{ title: 'Install', body: 'Add the package.', code: 'npm i my-lib', lang: 'sh' },
{ title: 'Call it', body: 'One function.', code: "parse('1 + 2'); // 3", lang: 'js' },
]} />

Code is highlighted at build time (light and dark themes).

Ready when you are

Read the guide, then try the playground.

npm i my-lib
src/pages/example.astro
<CallToAction
title="Ready when you are"
body="Read the guide, then try the playground."
primary={{ label: 'Read the docs', href: '/docs/' }}
secondary={{ label: 'Quick start', href: '/docs/quick-start/' }}
>
<InstallCommand command="npm i my-lib" />
</CallToAction>

The copy button appears only where the Clipboard API is available. GalleryStrip is shown on the Gallery page.

Keep the injected route, the header, footer and meta tags, and write only the body:

astro.config.mjs
components: { Landing: './src/components/MyLanding.astro' },
src/components/MyLanding.astro
---
import { Hero, Section, Features, GalleryStrip } from 'astro-project-site/components';
import config from 'astro-project-site/config';
const landing = config.landing || {};
---
<Hero title={config.name} lead={config.tagline} install={config.install} primary={landing.hero?.primary} />
<Section title="Benchmarks"><p>…your own section…</p></Section>
<Features items={landing.features?.items ?? []} />
<GalleryStrip limit={6} kinds={['demo']} />

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 }).

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:

src/pages/index.astro
---
import { BaseLayout, Hero, Section, Steps, CallToAction, Live } from 'astro-project-site/components';
import config from 'astro-project-site/config';
import demo from '../demos/hello.html?raw';
---
<BaseLayout>
<Hero title={config.name} lead={config.tagline} install={config.install}
primary={{ label: 'Docs', href: '/docs/' }}>
<div slot="live" class="site-container">
<Live code={demo} mode="iframe" editable title="hello.html" />
</div>
</Hero>
<Section title="How it works" tone="surface">
<Steps items={[{ title: 'Install', body: 'Add it.', code: 'npm i my-lib', lang: 'sh' }]} />
</Section>
<CallToAction title="Try it" primary={{ label: 'Playground', href: '/apps/hello/' }} />
</BaseLayout>

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.

<status-pill label="it runs"></status-pill> <status-pill label="in the page" tone="green"></status-pill>
A Live example inside the docs, as it would sit in the hero #
astro-project-site

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

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