Back to Documentation

Astro.js Pages Directory Structure Guidelines

This document outlines best practices for organizing the pages directory in our Astro.js project. As our site grows, maintaining a clean and logical structure becomes crucial for easier maintenance and collaboration.

Core Principles

  1. Predictability: File locations should be intuitive and follow conventions
  2. Scalability: Structure should accommodate growth without becoming chaotic
  3. Discoverability: Developers should be able to quickly find what they're looking for
  4. DRY (Don't Repeat Yourself): Minimize duplication through shared layouts and components

Pages Directory Structure

The src/pages directory in Astro.js directly maps to your site's routes. Here's our recommended organization:

src/pages/
├── index.astro            # Homepage
├── 404.astro              # Custom 404 error page
├── about.astro            # About page
│
├── blog/                  # Blog section
│   ├── index.astro        # Blog landing page
│   ├── [slug].astro       # Dynamic blog post page
│   └── category/
│       └── [category].astro  # Dynamic category page
│
├── projects/              # Projects section
│   ├── index.astro        # Main projects listing
│   └── [slug].astro       # Individual project page
│
├── art-gallery.astro      # Art gallery page
├── code-gallery.astro     # Code gallery page
│
└── dev/                   # Development/Testing pages
    ├── index.astro        # Dev homepage/directory
    ├── code-examples.astro  # Code examples and syntax highlighting
    ├── theme-system.astro # Theme system testing
    └── components/        # Component testing pages
        └── carousel.astro # Carousel component test

Guidelines for Creating New Pages

  1. Root-Level Pages:

    • Only place standalone/primary pages at the root level
    • Examples: homepage, about, contact, 404, etc.

  2. Section Directories:

    • Group related pages in dedicated directories
    • Each section should have its own index.astro as an entry point
    • Use descriptive directory names that match the site's information architecture

  3. Dynamic Routes:

    • Use Astro's dynamic route parameters (e.g., [slug].astro) for content-based pages
    • Keep dynamic route handlers organized within their relevant section directory

  4. Development Pages:

    • Keep all development, testing, and prototype pages in the /dev directory
    • These pages should not be linked from production sections
    • Consider protecting dev routes in production using middleware

Best Practices

  1. Consistent Naming Conventions:

    • Use kebab-case for page and directory names (e.g., about-us.astro, not aboutUs.astro)
    • Be descriptive but concise with filenames
    • Use index.astro for section landing pages

  2. Route Organization:

    • Match URL structure to directory structure
    • Group related functionality together
    • Consider user journey when organizing directories

  3. Avoid Deep Nesting:

    • Limit directory depth to 3-4 levels when possible
    • Excessive nesting makes the codebase harder to navigate

  4. Documentation:

    • Add comments at the top of complex pages explaining their purpose
    • Document unusual routing patterns or page behaviors

  5. Code Organization Within Pages:

    • Keep page components focused and consider extracting complex logic to separate components
    • Use layouts consistently across related pages

Special Cases

Internationalization (i18n)

If implementing multiple languages, consider one of these approaches:

# Option 1: Language directories at root level
src/pages/
├── en/
│   ├── index.astro
│   └── about.astro
├── fr/
│   ├── index.astro
│   └── about.astro

# Option 2: Using Astro's i18n routing
src/pages/
├── index.astro       # Default language (e.g., English)
├── about.astro
├── fr/
│   ├── index.astro   # French homepage
│   └── about.astro   # French about page

API Routes

For API endpoints, keep them organized in their own directory:

src/pages/api/
├── newsletter/
│   ├── subscribe.js
│   └── unsubscribe.js
└── auth/
    ├── login.js
    └── logout.js

Maintenance and Refactoring

As the project grows:

  1. Periodically review the pages directory structure to ensure it remains logical
  2. Consider refactoring when sections become too large or purposes change
  3. Update this documentation when new patterns emerge or conventions change

References