Small
One module you can read in an afternoon.
The page at / comes in three levels of control:
landing option fills the built-in page. Most sites stop here.components.Landing swaps the page body, keeping the shared header and footer.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).
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.
Parses things, quickly. No dependencies.
npm i my-libOptional content under the actions.
<status-pill label="hero slot"></status-pill><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.
The short version.
One module you can read in an afternoon.
Ships its own TypeScript types.
Plain HTML, any bundler, or none.
<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.
Add the package.
npm i my-libOne function.
parse('1 + 2'); // 3<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).
<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:
components: { Landing: './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:
---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>