Astro

Documentation sites sit awkwardly between two worlds. Their readers mostly want text, and text is best served as plain HTML that arrives fast and is indexable by a search engine. But the same product usually has a few genuinely interactive pieces — a live search box, a pricing calculator, a component playground, an account widget — and those pieces usually already exist somewhere in the organisation as React, Vue, or Svelte components. The classic static site generators handle the first case and force you to bolt the second one on with a hand-written bundle and a mounting script. The single-page application frameworks handle the second case and impose its cost on the first, because a reader of a reference manual ends up downloading a runtime to render text that could have been in the HTML from the start.

Astro was designed for exactly that middle position. It is a web framework that treats content as the primary material and rendering as a build-time operation. A page is HTML by default; no JavaScript is sent to the browser unless a component explicitly asks to be interactive. When an interactive component does appear, it is loaded and hydrated on its own, as an isolated island, so the cost of an interactive widget on one page never becomes the cost of the whole site. The result is that a documentation set with a search box and a component gallery can still ship a tiny bundle, and a marketing site can use a React charting library in a single hero section without turning the whole page into a React application.

The model has a few moving parts, and this chapter builds them in the order you will meet them. The first is the component model: a .astro file is a template with a script block in frontmatter and scoped styles, and it is rendered to HTML at build time. The second is the island model: a client directive attached to a framework component decides when, if ever, that component hydrates in the browser. The third is the content model: Markdown and MDX files live in collections with a schema, so a missing title or a malformed date is a build error rather than a broken page. The fourth is the extension model: integrations bring in a UI framework, an image pipeline, a sitemap generator, or an entire documentation theme without changing how your own components are written.

The practical result is a tool that sits comfortably next to the rest of a modern stack. Content authors work in Markdown and never encounter a component lifecycle. Developers reuse the components the company already has. The build produces a folder of static files that can be dropped on any object storage, while a server adapter is available for the small number of routes that genuinely need a request. The Starlight theme turns the framework into a complete documentation site in a single command, and the built-in image pipeline handles the asset work that documentation sites always seem to be short on.

By the end of this chapter you should be able to create a project and understand its layout, explain what an island is and when each hydration strategy is appropriate, define a content collection with a schema and render its entries, and compose components from several UI frameworks on the same page without giving up on the static output. The pages that follow cover the framework itself, the first hour with a project, the content system, and the component and integration model.

Chapters

Found an issue with this content?

Tell us what could be improved.