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

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

.astro
.md
.mdx (with the MDX Integration installed)
.html
.js/.ts (as endpoints)

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 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:

Read more <a href="/authors/sonali/">about Sonali</a>.

Astro Pages

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

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

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

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.

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

This is my page, written in **Markdown.**

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

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

For a custom 500 error page to show for pages that are rendered on demand, create the file src/pages/500.astro. This custom page is not available for prerendered pages and can’t be prerendered.

If an error occurs rendering this page, your host’s default 500 error page will be shown to your visitor.

Added in: astro@4.10.3 New

During development, if you have a 500.astro, the error thrown at runtime is logged in your terminal, as opposed to being shown in the error overlay.

`error`

Added in: astro@4.11.0 Beta

src/pages/500.astro is a special page that is automatically passed an error prop for any error thrown during rendering. This allows you to use the details of an error (e.g. from a page, from middleware, etc.) to display information to your visitor.

The error prop’s data type can be anything, which may affect how you type or use the value in your code:

---
interface Props {
    error: unknown
}

const { error } = Astro.props
---

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

To avoid leaking sensitive information when displaying content from the error prop, consider evaluating the error first, and returning appropriate content based on the error thrown. For example, you should avoid displaying the error’s stack as it contains information about how your code is structured on the server

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:

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

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.

<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:

---
export const partial = true;
---
<div>I was clicked!</div>

See the htmx documentation for more details on using htmx.

Create GitHub Issue

Send us feedback