Routing and nested pages
Static routes, dynamic routes, nested directories, pagination and the 404 page — a routing tour.
Astro 1:1 maps file paths under src/pages/ to URL paths. That rule alone covers most of what you need.
The mapping
| File | URL |
|---|---|
src/pages/index.astro |
/ |
src/pages/about.astro |
/about |
src/pages/library/index.astro |
/library |
src/pages/library/categories/guides.astro |
/library/categories/guides |
Directories nest naturally. Do not fight it — this site uses /library, /library/articles/[slug] and /library/categories/[category] as its three levels.
Dynamic routes
Wrap the file name in brackets:
src/pages/library/articles/[slug].astro
Export getStaticPaths so the build knows every URL it must produce:
import { getCollection } from 'astro:content';
export async function getStaticPaths() {
const articles = await getCollection('articles');
return articles.map((entry) => ({
params: { slug: entry.slug },
props: { entry },
}));
}
The static build emits one real directory per article — deep-linkable, crawlable, and cacheable forever.
Nested dynamic layouts
You can nest [parameters] at any level:
src/pages/docs/[section]/[slug].astro
Both params values arrive on Astro.params.
The 404 page
A file at src/pages/404.astro becomes dist/404.html and is served for unknown paths. Give it a friendly link back to the home page.
Nested output you can verify
After astro build, the filesystem mirrors the site map:
dist/library/articles/content-collections/index.html
dist/library/categories/guides/index.html
That mirror is one of the nicest properties of a static site: what you test locally is exactly what a CDN will serve.