File Routing Conventions

A handful of conventions cover most routing needs — nested folders, `index.astro`, and `_underscored` files that aren't served.

3 min read Level 1/5 #astro#routing#file-based

What you'll learn

Nest pages with folders
Know what `_filename` does
Recognize `.html` and `.md` as routes

A few patterns to internalize:

Nesting via Folders

src/pages/
├── index.astro          → /
├── about.astro          → /about
├── blog/
│   ├── index.astro      → /blog
│   └── post.astro       → /blog/post
└── docs/
    ├── getting-started.md  → /docs/getting-started
    └── advanced/
        └── hooks.astro     → /docs/advanced/hooks

Folders nest URLs. index.<ext> is the default page for that folder.

Leading Underscore — Not a Route

A file or folder starting with _ is excluded from routing. Useful for partials, shared helpers, or local components that happen to live near the pages.

src/pages/
├── blog/
│   ├── index.astro          → /blog
│   ├── post.astro           → /blog/post
│   └── _BlogList.astro      → NOT a route (helper component)

The same applies to folders — src/pages/_drafts/post.astro is not served.

Trailing Slash

By default, /about works. /about/ also works (Astro normalizes). You can configure the preferred form in astro.config.mjs with trailingSlash.

Routes From Imports

Pages can import normal components and helpers. The import path doesn’t affect routing — only the page file’s location in src/pages/ does.

---
// src/pages/about.astro
import Card from "../components/Card.astro";
import { formatDate } from "../lib/dates.ts";
---

<Card>About us</Card>

Up Next

A single file can handle many similar URLs — dynamic routes.

Dynamic Routes →