Pages
Pages are a special type of Astro component that live in the src/pages/
subdirectory. They are responsible for handling routing, data loading, and overall page layout for every HTML page in your website.
File-based routing
Section titled File-based routingAstro leverages a routing strategy called file-based routing. Every .astro
file in your src/pages
directory becomes a page or an endpoint on your site based on its file path.
📚 Read more about Routing in Astro
Page HTML
Section titled Page HTMLAstro Pages must return a full <html>...</html>
page response, including <head>
and <body>
. (<!doctype html>
is optional, and will be added automatically.)
---
// Example: src/pages/index.astro
---
<html>
<head>
<title>My Homepage</title>
</head>
<body>
<h1>Welcome to my website!</h1>
</body>
</html>
Leveraging Page Layouts
Section titled Leveraging Page LayoutsTo 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.
---
// Example: 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 Pages
Section titled Markdown PagesAstro also treats any Markdown (.md
) files inside of /src/pages/
as pages in your final website. 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
front matter property to specify a layout component that will wrap their Markdown content in a full <html>...</html>
page document.
---
# Example: 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.
Non-HTML Pages
Section titled Non-HTML PagesNon-HTML pages, like .json
or .xml
, or even assets such as images, can be built using API routes commonly referred to as File Routes.
File Routes are script files that end with the .js
or .ts
extension and are located within the src/pages/
directory.
Built filenames and extensions are based on the source file’s name, ex: src/pages/data.json.ts
will be built to match the /data.json
route in your final build.
In SSR (server-side rendering) the extension does not matter and can be omitted. This is because no files are generated at build time. Instead, Astro generates a single server file.
// Example: src/pages/builtwith.json.ts
// Outputs: /builtwith.json
// File routes export a get() function, which gets called to generate the file.
// Return an object with `body` to save the file contents in your final build.
export async function get() {
return {
body: JSON.stringify({
name: 'Astro',
url: 'https://astro.build/',
}),
};
}
API Routes receive an APIContext
object which contains params and a Request:
import type { APIContext } from 'astro';
export async function get({ params, request }: APIContext) {
return {
body: JSON.stringify({
path: new URL(request.url).pathname
})
};
}
Optionally you can also type your API route functions using the APIRoute
type. This will give you better error messages when your API route returns the wrong type:
import type { APIRoute } from 'astro';
export const get: APIRoute = ({ params, request }) => {
return {
body: JSON.stringify({
path: new URL(request.url).pathname
})
};
};
Custom 404 Error Page
Section titled Custom 404 Error PageFor 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.