Create routes with files

Files under src/pages/ become public routes. The file’s path decides the URL:

src/pages/index.astro        → /
src/pages/about.astro        → /about/
src/pages/docs/install.astro → /docs/install/

Astro uses the file and folder names as the route table. You do not register these pages in another configuration file, and there is no router object to maintain. Adding a route is creating a file. Removing a route is deleting one.

This is file-based routing, and its practical benefit goes beyond saving setup. The mapping works in both directions. Given a file, you know its URL. Given a URL, you know which file renders it. If /docs/install/ fails, you should be able to find its source without searching the entire project — so keep the hierarchy obvious.

Pages can be .astro, Markdown, MDX when configured, HTML, or endpoint files such as .ts. The extension affects how the route produces its response: an .astro page renders a template, a Markdown page renders its content, a .ts endpoint returns whatever response your code constructs.

Try it. Create two new routes:

mkdir -p src/pages/guides
touch src/pages/contact.astro src/pages/guides/index.astro

Give each file a minimal heading, then open /contact/ and /guides/ in the dev server. Run a production build and find their generated output under dist/ — one folder with an index.html per route in the default configuration.

Two things to watch. First, avoid creating two page files that compete for the same route, such as src/pages/blog.astro next to src/pages/blog/index.astro. Both want /blog/, and you should not have to remember which one wins. Keep one.

Second, remember that your host may normalize trailing slashes or filenames differently from development. A URL that works locally as /about may redirect or 404 in production depending on the platform. Verify important URLs on the deployed site, not only in the dev server.