Astro uses file-based routing to generate your build URLs based on the file layout of your project
src/pages/ directory. When a file is added to the
src/pages directory of your project, it is automatically available as a route based on its filename.
Static routesSection titled Static routes
Astro Components (
.astro) and Markdown Files (
.md) in the
src/pages directory automatically become pages on your website. Each page’s route corresponds to its path and filename within the
Navigating between pagesSection titled Navigating between pages
Astro uses standard HTML
<a> elements to navigate between routes. There is no framework-specific
<Link> component provided.
Dynamic routesSection titled Dynamic routes
A single Astro Page component can also specify dynamic route parameters in its filename to generate multiple routes that match a given criteria. You can create several related pages at once, such as author pages, or a page for each blog tag. Named parameters allow you to specify values for “named” levels of these route paths, and rest parameters allow for more flexible “catch-all” routes.
Astro pages that create dynamic routes must:
[bracket]notation to identify the dynamic parameters
getStaticPaths()function to specify exactly which paths will be pre-rendered by Astro.
Named ParametersSection titled Named Parameters
You can generate routes with a
[named] parameter by providing your
getStaticPaths() function the values to use like so:
📚 Learn more about
Routes can be generated from multiple named parameters, at any level of the filepath:
The Section titled The Astro.params object
Astro components that generate routes dynamically have access to an
Astro.params object for each route. This allows you to use those generated parts of the URL in your component script and template.
Multiple dynamic route segments can be combined to work the same way.
Rest parametersSection titled Rest parameters
If you need more flexibility in your URL routing, you can use a rest parameter in your
.astro filename as a universal catch-all for file paths of any depth by adding three dots (
...) inside your brackets.
Matched parameters will be passed as a query parameter (
slug in the example) to the page.
Example: Rest parametersSection titled Example: Rest parameters
For a real-world example, you can implement GitHub’s file viewer with the following named and rest paramenters:
In this example, a request for
/withastro/astro/tree/main/docs/public/favicon.svg would result in the following parameters being available to the page:
Example: Dynamically create a top level root pageSection titled Example: Dynamically create a top level root page
To dynamically create an index.html at root level (e.g. for content fetched from a headless CMS), include an object with
slug: undefined in your
Route Priority OrderSection titled Route Priority Order
It’s possible for multiple routes to match the same URL path. For example each of these routes would match
Astro needs to know which route should be used to build the page. To do so, it sorts them according to the following rules:
- Static routes without path parameters will take precedence over all other routes
- Dynamic routes using named parameters take precedence over rest parameters
- Rest parameters have the lowest priority
- Ties are resolved alphabetically
Given the example above, here are a few examples of how the rules will match a requested URL to the route used to build the HTML:
pages/posts/create.astro- Will build
pages/posts/[pid].astro- Will build
/posts/abc, etc. But not
pages/posts/[...slug].astro- Will build
/posts/a/b/c, etc. But not
PaginationSection titled Pagination
Astro supports built-in pagination for large collections of data that need to be split into multiple pages. Astro will generate common pagination properties, including previous/next page URLs, total number of pages, and more.
Paginated route names should use the same
[bracket] syntax as a standard dynamic route. For instance, the file name
/astronauts/[page].astro will generate routes for
/astronauts/2, etc, where
[page] is the generated page number.
You can use the
paginate() function to generate these pages for an array of values like so:
This generates the following pages, with 2 items to a page:
/astronauts/1- Page 1: Displays “Neil Armstrong” and “Buzz Aldrin”
/astronauts/2- Page 2: Displays “Sally Ride” and “John Glenn”
The Section titled The page prop
When you use the
paginate() function, each page will be passed its data via a
page prop. The
page prop has many useful properties, but here are the highlights:
- page.data - array containing the page’s slice of data that you passed to the
- page.url.next - link to the next page in the set
- page.url.prev - link to the previous page in the set
Complete API referenceSection titled Complete API reference
Nested PaginationSection titled Nested Pagination
A more advanced use-case for pagination is nested pagination. This is when pagination is combined with other dynamic route params. You can use nested pagination to group your paginated collection by some property or tag.
For example, if you want to group your paginated Markdown posts by some tag, you would use nested pagination by creating a
/src/pages/[tag]/[page].astro page that would match the following URLS:
Nested pagination works by returning an array of
paginate() results from
getStaticPaths(), one for each grouping.
In the following example, we will implement nested pagination to build the URLs listed above:
Excluding pagesSection titled Excluding pages
You can exclude pages, or even whole directories from being built by prefixing their names with an underscore (
This allows you to create private pages, and also to co-locate tests, utilities, and components with their related pages, preventing them from being built into
.html files and placed into the
In this example, only
src/pages/posts/post1.md will be built as page routes and HTML files.