Skip to content

Pages

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 files

Section titled Supported page files

Astro supports the following file types in the src/pages/ directory:

File-based routing

Section 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.

Read more about Routing in Astro.
Section 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 example.com:

src/pages/index.astro
Read more <a href="/authors/sonali/">about Sonali</a>.

Astro Pages

Section titled Astro Pages

Astro pages use the .astro file extension and support the same features as Astro components.

src/pages/index.astro
---
---
<html lang="en">
  <head>
    <title>My Homepage</title>
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

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 <head> and <body> elements into your own layout components. You can use as many or as few layout components as you’d like.

src/pages/index.astro
---
import MySiteLayout from '../layouts/MySiteLayout.astro';
---
<MySiteLayout>
  <p>My page content, wrapped in a layout!</p>
</MySiteLayout>
Read more about layout components in Astro.

Markdown/MDX Pages

Section 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.

Collections of Markdown or MDX page content in src/content/ can be used to generate pages dynamically.

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.

src/pages/page.md
---
layout: '../layouts/MySiteLayout.astro'
title: 'My Markdown page'
---
# Title


This is my page, written in **Markdown.**
Read more about Markdown in Astro.

HTML Pages

Section 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 Page

Section titled Custom 404 Error Page

For a custom 404 error page, you can create a 404.astro or 404.md file in src/pages.

This will build to a 404.html page. Most deploy services will find and use it.

Custom 500 Error Page

Section titled Custom 500 Error Page

For a custom 500 error page, you can create a 500.astro in src/pages.

If an error occurs in this file, it will default to the host 500 error page.

Retrieve The Error

Section titled Retrieve The Error

Added in: astro@4.10.0 New

500.astro accepts an error prop. It can be anything, so make sure to handle it properly:

src/pages/500.astro
---
interface Props {
    error: unknown
}


const { error } = Astro.props
---


<div>{error instanceof Error ? error.message : 'Unknown error'}</div>

Usage In Development

Section titled Usage In Development

Added in: astro@4.10.0 New

You can use your custom 500 error page in development by setting the ASTRO_CUSTOM_500 environment variable to 'true'. For example using a .env file:

.env
ASTRO_CUSTOM_500=true

Or inline:

Terminal window
ASTRO_CUSTOM_500=true astro dev

If an error occurs in this file, it will default to the error overlay.

Page Partials

Section titled Page Partials

Added in: astro@3.4.0

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.

Partials, when combined with a rendering library, provide an alternative to Astro islands and <script> tags for building dynamic content in Astro.

Page files that can export a value (e.g. .astro , .mdx) can be marked as partials.

Configure a file within the src/pages/ directory to be a partial by adding the following export:

src/pages/partial.astro
---
export const partial = true;
---


<li>I'm a partial!</li>

The export const partial must be identifiable statically. It can have the value of:

  • The boolean true.
  • An environment variable using import.meta.env such as import.meta.env.USE_PARTIALS.

Using with a library

Section 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.

src/pages/index.astro
<html>
  <head>
    <title>My page</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
</html>
<section>
  <div id="parent-div">Target here</div>


  <button hx-post="/partials/clicked/"
    hx-trigger="click"
    hx-target="#parent-div"
    hx-swap="innerHTML"
  >
      Click Me!
  </button>
</section>

The .astro partial must exist at the corresponding file path, and include an export defining the page as a partial:

src/pages/partials/clicked.astro
---
export const partial = true;
---
<div>I was clicked!</div>

See the htmx documentation for more details on using htmx.