Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Pages, Layouts and Routing

File-Based Routing in Astro

See how files in src/pages become URLs in Astro, how index files, nested folders and file types map to routes, and how links and route priority work.

Astro does not need a router configuration. The files you put in src/pages/ are the routes. Create a file, and the matching URL exists. Rename a file, and the URL changes. This keeps the structure of your site visible in your folder tree and makes it easy for new teammates to find the code behind any address.

In this lesson you will learn the mapping rules, which file types can be pages, how to link between them, and how Astro decides between overlapping routes.

Pages become URLs

Only files inside src/pages/ create routes. The file name (without extension) and the folders above it make the path.

File in src/pages/ URL
index.astro /
about.astro /about
contact/index.astro /contact
blog/index.astro /blog
blog/first-post.md /blog/first-post
docs/getting-started/install.astro /docs/getting-started/install

Both about.astro and about/index.astro give you /about. Use whichever you prefer, but do not create both: they would collide.

From file to URL

pages/about.astro becomes /about
pages/blog/index.astro becomes /blog
1 / 2

File types that can be pages

  • .astro components are the most common page type.
  • .md and .mdx files render as pages with a layout. See Markdown pages.
  • .html files are used as they are, with no components or expressions.
  • .js and .ts files can be endpoints that return data (JSON, images, feeds). The file pages/data.json.ts serves /data.json. Endpoints are explored in the SSR chapter.

Files and folders that start with an underscore, such as _helpers.ts or _components/Card.astro, are ignored by the router. This lets you keep helper code next to a page without publishing it.

TEXT
src/pages/
โ”œโ”€โ”€ index.astro
โ”œโ”€โ”€ about.astro
โ”œโ”€โ”€ _partials/
โ”‚   โ””โ”€โ”€ Hero.astro        (not a route)
โ”œโ”€โ”€ blog/
โ”‚   โ”œโ”€โ”€ index.astro
โ”‚   โ””โ”€โ”€ hello-world.md
โ””โ”€โ”€ api/
    โ””โ”€โ”€ status.json.ts    (endpoint at /api/status.json)

Linking between pages

Pages are plain HTML, so links are plain <a> tags. Use root-relative paths so they work from any page:

ASTRO
<nav>
  <a href="/">Home</a>
  <a href="/about">About</a>
  <a href="/blog">Blog</a>
</nav>

If you configured a base, prefix links with import.meta.env.BASE_URL so they keep working under a subfolder:

ASTRO
---
const base = import.meta.env.BASE_URL.replace(/\/$/, "");
---
<a href={`${base}/about`}>About</a>

To highlight the current page, read Astro.url.pathname in the component script:

ASTRO
---
const { pathname } = Astro.url;
const links = [
  { href: "/", text: "Home" },
  { href: "/about", text: "About" },
];
---
<nav>
  {links.map((l) => (
    <a href={l.href} aria-current={pathname === l.href ? "page" : undefined}>{l.text}</a>
  ))}
</nav>

aria-current="page" is also an accessibility win: screen readers announce the current page.

Route priority

Static routes can overlap with dynamic ones, which you will meet in Dynamic routes. Astro uses a fixed priority order so results are predictable:

  1. Reserved routes (such as Astro's internal ones).
  2. Routes with more path segments win over routes with fewer.
  3. Static routes win over dynamic ones (/posts/create beats /posts/[id]).
  4. Named parameters [id] win over rest parameters [...path].
  5. Pre-rendered dynamic routes win over server-rendered ones.
  6. Ties break alphabetically.

Stand-in: mapping files to routes

This stand-in converts a list of page files into routes, ignores underscore files and finds duplicates, which is the behavior the real router implements.

Node.js Stand-in: build a route table from files

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Stand-in: current-page navigation

Highlighting the active link is a tiny function of the current path. Try different paths and watch the aria-current attribute move.

Node.js Stand-in: render a nav for a path

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Common mistakes

  • Putting pages outside src/pages/. They will not become routes.
  • Using both about.astro and about/index.astro. The build reports a duplicate.
  • Forgetting the leading slash in links. href="about" is relative to the current page and breaks inside folders.
  • Naming a component folder inside pages/ without an underscore. Every file in pages/ is a route, so prefix helper folders with _ or keep them in src/components/.
  • Mixing trailing slash styles. Set trailingSlash in the config and stick with it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file creates the URL /blog?

    An index file inside a folder in src/pages maps to the folder's path. Only src/pages creates routes.
  2. 2. What happens to src/pages/_partials/Hero.astro?

    Files and folders that start with an underscore are not turned into routes.
  3. 3. Which route wins for the URL /posts/create when both pages/posts/[id].astro and pages/posts/create.astro exist?

    Static routes have higher priority than dynamic ones, so create.astro handles /posts/create.
  4. 4. What does src/pages/data.json.ts produce?

    JavaScript and TypeScript files in pages are endpoints. The double extension decides the served file name.

Summary

  • Files in src/pages/ map directly to URLs; index files represent their folder.
  • .astro, .md, .mdx, .html render pages; .js and .ts files are endpoints.
  • Underscore-prefixed files and folders are ignored by the router.
  • Use root-relative links and Astro.url.pathname to mark the current page.
  • Priority rules favor longer, static and named routes over shorter, dynamic and rest routes.

Next: Layouts and Slots