Should I do it? Here are the pros and cons
Posted on 30th May 2026 at 10:40 by Admin
You can turn your /src/pages/ branch into a content collection.
In Astro, you can define any folder in /src/content/ as a collection—whether it is for blog posts, documentation, or deeply nested hierarchical pages.
Here is a breakdown of how it works and the trade-offs to consider.
How to do it
Instead of having physical files deeply nested in /src/pages/xxxx/yyyy/, you would move your Markdown or MDX files into a new collection, for example, /src/content/docs
Define the collection schema in src/content/config.ts.
Create a catch-all dynamic route file at src/pages/[…slug].astro.
In this file, you query the collection using getCollection(), map the slugs, and render the pages.
Pros: Why you should do it
-
Strict Type Safety: You can define a frontmatter schema (e.g., requiring title, description, and publishDate). Astro will throw build errors if any file is missing required fields or has the wrong data types.
-
Cleaner Project Structure: You can organize your files into nested subdirectories (e.g., /src/content/docs/api/auth.md) to keep your /src/pages/ directory clean.
-
Better Querying: Content collections make it exceptionally easy to fetch related content, build breadcrumbs, or generate table-of-contents arrays across your deeply nested pages.
Cons: Why you might want to keep /src/pages/
-
Loss of File-Based Routing: You lose Astro’s default file-based routing. Every URL path relies on a single […slug].astro catch-all file, which can make debugging slightly more complex.
-
Component Mixing: You cannot easily mix pure UI components (.astro files without frontmatter) inside the collection folder. If you have a unique page in your hierarchy that just renders a component (like a “Contact Us” or “Dashboard” page), it cannot live in the content collection.
-
Boilerplate Code: You have to write the routing and rendering logic yourself inside […slug].astro using the <Content /> component renderer.
Implementation
I did it on 1 June following Gemini’s suggestions, and it was surproisingly easy
-
Convert any .astro files in /src/pages tree to MD or MDX, leaving 404.astro, sitemap.astro and select-pages-posts.astro. Move these to /src/pages.
-
Create /content/pages directory. Move all MD(X) files and their folders from src/pages to src/content/pages, leaving behind 404.astro, sitemap.astro and select-pages-posts.astro.
-
Also leave behind /src/pages/posts which contains all the fancy routing stuff fo posts
-
Revise src/content.config.ts
-
Add src/pages/[…slug].astro
Conclusion
Good move.