Pages are files that live in the
src/pages/ subdirectory of your Astro project. They are responsible for handling routing, data loading, and overall page layout for every page in your website.
Supported page filesSection titled Supported page files
Astro supports the following file types in the
File-based routingSection titled File-based routing
Astro leverages a routing strategy called file-based routing. Each file in your
src/pages/ directory becomes an endpoint on your site based on its file path.
A single file can also generate multiple pages using dynamic routing. This allows you to create pages even if your content lives outside of the special
/pages/ directory, such as in a content collection or a CMS.
Link between pagesSection titled Link between pages
Write standard HTML
<a> elements in your Astro pages to link to other pages on your site. Use a URL path relative to your root domain as your link, not a relative file path.
For example, to link to
https://example.com/authors/sonali/ from any other page on
Astro PagesSection titled Astro Pages
Astro pages use the
.astro file extension and support the same features as Astro components.
A page must produce a full HTML document. If not explicitly included, Astro will add the necessary
<!DOCTYPE html> declaration and
<head> content to any
.astro component located within
src/pages/ by default. You can opt-out of this behavior on a per-component basis by marking it as a partial page.
To avoid repeating the same HTML elements on every page, you can move common
<body> elements into your own layout components. You can use as many or as few layout components as you’d like.
Markdown/MDX PagesSection titled Markdown/MDX Pages
Astro also treats any Markdown (
.md) files inside of
src/pages/ as pages in your final website. If you have the MDX Integration installed, it also treats MDX (
.mdx) files the same way. These are commonly used for text-heavy pages like blog posts and documentation.
Page layouts are especially useful for Markdown files. Markdown files can use the special
layout frontmatter property to specify a layout component that will wrap their Markdown content in a full
<html>...</html> page document.
HTML PagesSection titled HTML Pages
Files with the
.html file extension can be placed in the
src/pages/ directory and used directly as pages on your site. Note that some key Astro features are not supported in HTML Components.
Custom 404 Error PageSection titled Custom 404 Error Page
For a custom 404 error page, you can create a
404.md file in
This will build to a
404.html page. Most deploy services will find and use it.
Page PartialsSection titled Page Partials
Additionally, partials should not be used if the component contains scoped styles or scripts, as these elements will be stripped from the HTML output. If you need scoped styles, it is better to use regular, non-partial pages along with a frontend library that knows how to merge the contents into the head.
Partials are page components located within
src/pages/ that are not intended to render as full pages.
Like components located outside of this folder, these files do not automatically include the
<!DOCTYPE html> declaration, nor any
<head> content such as scoped styles and scripts.
However, because they are located in the special
src/pages/ directory, the generated HTML is available at a URL corresponding to its file path. This allows a rendering library (e.g. htmx, Stimulus, jQuery) to access it on the client and load sections of HTML dynamically on a page without a browser refresh or page navigation.
Page files that can export a value (e.g.
.mdx) can be marked as partials.
Configure a file within the
src/pages/ directory to be a partial by adding the following export:
export const partial must be identifiable statically. It can have the value of:
- The boolean
- An environment variable using import.meta.env such as
Using with a librarySection titled Using with a library
Partials are used to dynamically update a section of a page using a library such as htmx.
The following example shows an
hx-post attribute set to a partial’s URL. The content from the partial page will be used to update the targeted HTML element on this page.
.astro partial must exist at the corresponding file path, and include an export defining the page as a partial:
See the htmx documentation for more details on using htmx.Learn