Use nested and index pages

An index page represents the folder URL. When a visitor requests /blog/, Astro answers with the index file inside the blog folder:

src/pages/blog/index.astro   → /blog/
src/pages/blog/archive.astro → /blog/archive/

This mirrors a familiar static-site structure and keeps related routes together. Web servers have served index.html for directory URLs for decades, and Astro’s build output makes that literal. With the default static output, src/pages/blog/index.astro becomes dist/blog/index.html, and archive.astro becomes dist/blog/archive/index.html.

A deeper index works the same way, at any level:

src/pages/docs/api/index.astro → /docs/api/

When should you switch from a flat file to a folder with an index? Both src/pages/blog.astro and src/pages/blog/index.astro produce /blog/, so pick one form and stay with it. My advice is to create the folder as soon as a section grows a second page. Then /blog/ and everything under it live in one directory, and the source tree reads like the sitemap.

Use folders when they reflect the public information hierarchy. The URL is part of the interface: /docs/api/ tells the reader where they are before the page loads. Do not nest files only to organize the source if you do not want that nesting in the URL, because every folder under src/pages/ becomes a visible URL segment.

Shared components do not belong under src/pages/ unless they should become routes. Put a reusable blog card under src/components/, not beside page files where it could be mistaken for a public page. If a helper file must sit near the pages that use it, prefix its name with an underscore, such as src/pages/blog/_PostCard.astro. Astro excludes underscore-prefixed files from routing.

The realistic failure here is a silent URL change. Moving about.astro into a folder moves its public address, and inbound links to the old URL start returning 404 without any build warning.

Move a page into a folder and run the build. Confirm the old URL no longer exists under dist/, then add a redirect when the URL was already public.