Starlight Layouts

What this site is

Starlight ships a full documentation layout out of the box, and it also lets you override almost any piece of that layout with your own component. This site is both:

• a tutorial that walks through how component overrides work, and how to branch a single override so most pages keep Starlight’s default layout while a few pages opt into something custom, and
• a live demo where each layout built in the tutorial has a real route you can visit and compare side-by-side with the default.

This very page is an example: it uses Starlight’s built-in template: splash frontmatter field, no overrides required. The tutorial picks up from there.

The project itself is a pnpm monorepo: this Starlight app lives in apps/site, and each of the four custom layouts is its own package under packages/. The tutorial builds up to that structure rather than assuming it — the first few pages work the same whether your project is a monorepo or not.

1. How overrides work

Learn which components are overridable and the Default import pattern that lets a custom component fall back to Starlight’s own markup.

2. Conditional defaults

Add a custom frontmatter field so a single override can serve both default pages and custom-layout pages.

3–6. Build four layouts

Full-width, minimal (chrome-free), a two-column layout with an extra aside panel, and a widget-grid dashboard — each with a matching demo route.

See the demos

Every layout built in the tutorial has a page under Layout demos in the sidebar so you can see it rendered for real.

Fill in a dashboard

Building the layout is only half the job — Guides covers what to actually put inside a dashboard’s widgets once you have the space.

7. Composing layout packages

How the four layouts became pnpm workspace packages, and how the app composes them without Starlight ever knowing packages exist.