Creating pages in Astro - Mechanics & Internals

Overview - Creating pages

What is it?

Creating pages in Astro means making the different screens or views users see when they visit a website. Each page is a file that tells Astro what content to show and how to arrange it. These pages can include text, images, and interactive parts. Astro uses simple files and folders to organize these pages so the website works smoothly.

Why it matters

Without pages, a website would be just one big jumble of content with no way to separate different topics or sections. Creating pages lets users find what they want easily, like chapters in a book. It also helps developers keep their work neat and organized, making updates and fixes faster and less confusing.

Where it fits

Before learning to create pages, you should understand basic HTML and how files and folders work on a computer. After mastering pages, you can learn about routing, layouts, and adding interactivity with components and scripts in Astro.

Mental Model

Core Idea

In Astro, each page is a file that acts like a chapter in a book, defining what content and structure the user sees when they visit a specific address.

Think of it like...

Creating pages in Astro is like organizing chapters in a cookbook: each chapter (page) has its own recipes (content) and order, making it easy for readers to find and enjoy what they want.

┌───────────────┐
│ src/pages/    │  ← Folder holding all pages
├───────────────┤
│ index.astro   │  ← Home page (root URL)
│ about.astro   │  ← About page (/about URL)
│ blog/         │  ← Folder for blog pages
│   ├ post1.astro│ ← Blog post 1 (/blog/post1 URL)
│   └ post2.astro│ ← Blog post 2 (/blog/post2 URL)
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Astro page files

Concept: Pages in Astro are created by adding .astro files inside the src/pages folder.

In your Astro project, the src/pages folder is special. Any .astro file you put here becomes a page on your website. For example, src/pages/index.astro is the homepage. If you add about.astro, it becomes the /about page. Each file contains HTML-like code that tells Astro what to show.

Result

You get a website with multiple pages accessible by different URLs matching the file names.

Knowing that pages are just files in a folder helps you organize your site naturally and predict how URLs map to files.

2

Foundation

Basic page structure in Astro

Concept: Each page file uses Astro syntax to define HTML content and can include components or scripts.

A simple page looks like this: --- // Frontmatter: place for scripts or imports ---

Hello from Astro!

The frontmatter section (between ---) is optional but useful for logic or importing components.

Result

The page renders with the defined HTML content when visited.

Understanding the frontmatter and template parts lets you mix static content with dynamic features easily.

3

Intermediate

Creating nested pages with folders

🤔Before reading on: do you think placing a file inside a folder changes its URL path? Commit to your answer.

Concept: Folders inside src/pages create nested URLs, letting you organize pages hierarchically.

If you create a folder inside src/pages, like blog/, and put post1.astro inside it, the URL becomes /blog/post1. This helps group related pages. For example: src/pages/blog/post1.astro → /blog/post1 src/pages/blog/post2.astro → /blog/post2 This structure matches how websites organize content by topics or sections.

Result

Users can visit nested URLs that reflect the folder structure, making navigation logical.

Knowing folder structure controls URLs helps you plan site navigation and SEO-friendly paths.

4

Intermediate

Using dynamic routes for flexible pages

🤔Before reading on: do you think you can create a page that changes based on URL parts without making many files? Commit to your answer.

Concept: Astro supports dynamic routes using special file names with brackets to capture URL parts as variables.

Instead of making many files for similar pages, you can create one dynamic page: src/pages/blog/[slug].astro Here, [slug] is a placeholder. Visiting /blog/post1 or /blog/post2 loads the same file but with different slug values. Inside the page, you can use the slug to fetch or show different content dynamically.

Result

You get flexible pages that change content based on the URL without extra files.

Dynamic routes reduce repetition and let you build scalable sites with many similar pages.

5

Intermediate

Adding metadata with frontmatter exports

🤔Before reading on: do you think you can add page-specific data like titles or descriptions inside the page file? Commit to your answer.

Concept: Astro pages can export metadata in frontmatter to customize page behavior or be used by layouts and tools.

Inside the frontmatter (---), you can export variables: --- export const title = 'About Us'; export const description = 'Learn about our team'; --- This metadata can be read by layouts or plugins to set page titles, descriptions, or other settings automatically.

Result

Pages carry their own data, making site-wide features like SEO easier to manage.

Embedding metadata in pages keeps content and settings together, improving maintainability.

6

Advanced

Using layouts to share page structure

🤔Before reading on: do you think every page needs to repeat the same header and footer code? Commit to your answer.

Concept: Layouts let you wrap pages with common structure like headers, footers, or navigation, avoiding repetition.

Create a layout component, e.g., src/layouts/BaseLayout.astro: --- const { title } = Astro.props; ---

Site Header

Site Footer

Then in a page: --- import BaseLayout from '../layouts/BaseLayout.astro'; export const title = 'Home'; ---

Welcome!

This shares common parts and lets pages focus on unique content.

Result

Pages have consistent look and feel with less duplicated code.

Layouts promote DRY (Don't Repeat Yourself) principles and make site-wide changes easy.

7

Expert

How Astro builds pages at runtime

🤔Before reading on: do you think Astro sends raw .astro files to the browser or pre-builds HTML? Commit to your answer.

Concept: Astro compiles .astro page files into static HTML at build time, sending minimal JavaScript to the browser.

When you build your site, Astro processes each page file, converting its template and components into plain HTML files. This means the browser gets fast-loading pages without waiting for JavaScript to render content. If you add interactive components, Astro loads their scripts only when needed. This approach improves performance and SEO.

Result

Websites built with Astro load quickly and work well on all devices.

Understanding Astro's build process explains why pages are fast and how to optimize interactivity.

Under the Hood

Astro treats each .astro file in src/pages as a template. During build, it parses these files, compiles their frontmatter and template into static HTML files. It resolves imports and components, rendering them to HTML strings. Dynamic routes generate multiple HTML files based on data or parameters. Interactive components are hydrated on the client only when needed, minimizing JavaScript. The build output is a static site or server-rendered pages depending on configuration.

Why designed this way?

Astro was designed to solve slow websites caused by heavy JavaScript. By pre-rendering pages to static HTML, it ensures fast load times and better SEO. The file-based routing matches familiar patterns from other frameworks, making it easy to learn. Dynamic routes and layouts add flexibility without sacrificing performance. This design balances developer experience with user experience.

src/pages/           (folder with page files)
  ├ index.astro       (→ /)
  ├ about.astro       (→ /about)
  ├ blog/            (folder for nested pages)
  │   ├ [slug].astro  (→ /blog/:slug dynamic route)
  │   └ post2.astro   (→ /blog/post2)
  ↓
Astro build process:
  └─> Parses .astro files
       ↓
  └─> Compiles to static HTML
       ↓
  └─> Outputs files in dist/ folder
       ↓
  └─> Serves static pages with minimal JS

Myth Busters - 4 Common Misconceptions

Quick: Does creating a file named about.astro automatically make it accessible at /about? Commit to yes or no.

Common Belief: If I add about.astro anywhere in the project, it becomes the /about page.

Reality: Only .astro files inside the src/pages folder (or configured pages folder) become pages with URLs matching their file path.

Why it matters: Placing page files outside src/pages means they won't be accessible as pages, causing confusion and broken links.

Quick: Do you think Astro pages always send JavaScript to the browser? Commit to yes or no.

Common Belief: Astro pages always load JavaScript like React or Vue apps do.

Reality: Astro pre-renders pages to static HTML and sends minimal or no JavaScript unless you add interactive components explicitly.

Why it matters: Expecting heavy JS can lead to unnecessary complexity; understanding Astro's static-first approach helps optimize performance.

Quick: Can you create dynamic routes by naming files with curly braces like {slug}.astro? Commit to yes or no.

Common Belief: Dynamic routes use curly braces in file names, like {slug}.astro.

Reality: Astro uses square brackets for dynamic routes, like [slug].astro; curly braces are not recognized.

Why it matters: Using wrong syntax breaks routing and causes pages not to load as expected.

Quick: Does wrapping a page in a layout automatically pass all page data to the layout? Commit to yes or no.

Common Belief: Layouts automatically receive all variables and metadata from the page without passing props.

Reality: Layouts only get data explicitly passed as props; you must pass variables like title manually.

Why it matters: Assuming automatic data passing leads to bugs where layouts show empty or wrong content.

Expert Zone

1

Astro's file-based routing supports advanced patterns like catch-all routes ([...rest].astro) for flexible URL matching.

2

Layouts can be nested, allowing complex page structures with multiple layers of shared UI.

3

Astro's partial hydration lets you load interactive components only when visible, improving performance on large pages.

When NOT to use

Creating pages with Astro is not ideal for highly dynamic, real-time applications needing constant client-side updates; frameworks like React or Vue SPA might be better. Also, if you need server-side rendering with user-specific data on every request, consider using Astro with SSR adapters or other SSR frameworks.

Production Patterns

In production, teams organize pages by feature folders, use dynamic routes for blogs or products, and combine layouts for consistent branding. They also leverage frontmatter metadata for SEO and automate sitemap generation. Partial hydration is used to keep pages fast while adding interactivity only where needed.

Connections

File System Routing

Creating pages in Astro builds on the idea of file system routing used in frameworks like Next.js and Nuxt.js.

Understanding file system routing helps grasp how URLs map to files, making page creation intuitive across modern web frameworks.

Static Site Generation (SSG)

Astro's page creation is tightly linked to static site generation, where pages are pre-built as HTML files.

Knowing SSG principles explains why Astro pages load fast and how build-time rendering differs from client-side rendering.

Book Publishing

Creating pages in Astro is like organizing chapters in a book, where each page file is a chapter with its own content and place.

This connection helps understand the importance of structure and navigation in both digital and physical content.

Common Pitfalls

#1 Page file placed outside src/pages folder

Wrong approach:

src/components/about.astro

// Trying to create /about page here

Correct approach:

src/pages/about.astro

// Correct location for page files

Root cause:

Misunderstanding that only files inside src/pages become pages with URLs.

#2 Using curly braces for dynamic routes

Wrong approach:

src/pages/blog/{slug}.astro

// Incorrect dynamic route syntax

Correct approach:

src/pages/blog/[slug].astro

// Correct dynamic route syntax

Root cause:

Confusing syntax conventions from other frameworks or languages.

#3 Not passing props to layouts

Wrong approach:

---
export const title = 'Home';
---

Welcome

// Layout won't receive title

Correct approach:

---
export const title = 'Home';
---

Welcome

Root cause:

Assuming layouts automatically get page variables without explicit prop passing.

Key Takeaways

Astro creates pages by placing .astro files inside the src/pages folder, mapping files to URLs naturally.

Folders inside src/pages create nested URLs, and dynamic routes use square brackets to capture URL parts.

Pages combine frontmatter for logic and metadata with template HTML to define content and structure.

Layouts help share common page parts like headers and footers, reducing repetition and improving consistency.

Astro pre-builds pages to static HTML for fast loading, sending JavaScript only when needed for interactivity.

Practice

1. What happens when you create a new .astro file inside the src/pages folder in an Astro project?

easy

A. You must register the page in a routing file for it to work.

B. The file is ignored unless you import it manually in another file.

C. A new webpage is automatically created with a URL matching the file name.

D. It creates a new component but not a page.

Solution

1. Step 1: Understand Astro's file-based routing

   Astro automatically creates routes from files in src/pages. Each .astro file becomes a page.

2. Step 2: Connect file name to URL

   The file name directly maps to the URL path, so creating a file adds a new page accessible by that URL.

3. Final Answer:

   A new webpage is automatically created with a URL matching the file name. -> Option C

4. Quick Check:

   File in src/pages = new page URL [OK]

Hint: Remember: pages folder files become URLs automatically [OK]

Common Mistakes:

• Thinking you must import page files manually
• Confusing components with pages
• Believing a routing config is needed

2. Which of the following is the correct way to create a homepage in Astro?

easy

A. Create a file named default.astro inside src/pages/home.

B. Create a file named home.astro inside src/pages.

C. Create a file named main.astro inside src/components.

D. Create a file named index.astro inside src/pages.

Solution

1. Step 1: Identify homepage naming convention

   In Astro, the homepage URL is /, which maps to index.astro in src/pages.

2. Step 2: Check folder and file placement

   The file must be directly inside src/pages and named index.astro to serve as homepage.

3. Final Answer:

   Create a file named index.astro inside src/pages. -> Option D

4. Quick Check:

   Homepage = src/pages/index.astro [OK]

Hint: Homepage file is always index.astro in pages folder [OK]

Common Mistakes:

• Naming homepage file anything other than index.astro
• Placing homepage file in components folder
• Using nested folders incorrectly for homepage

3. Given this file src/pages/about.astro with content:

<!-- src/pages/about.astro -->
<h1>About Us</h1>
<p>Welcome to our site.</p>

What URL will display this page when running the Astro dev server?

medium

A. http://localhost:3000/about

B. http://localhost:3000/about.astro

C. http://localhost:3000/about-us

D. http://localhost:3000/pages/about

Solution

1. Step 1: Map file path to URL

   The file about.astro inside src/pages maps to the URL path /about.

2. Step 2: Understand URL structure

   Astro removes the file extension and folder prefix src/pages from the URL, so the URL is /about.

3. Final Answer:

   http://localhost:3000/about -> Option A

4. Quick Check:

   File name = URL path [OK]

Hint: File name without extension = URL path [OK]

Common Mistakes:

• Including .astro extension in URL
• Adding 'pages' folder name to URL
• Guessing URL from page content

4. You created a file src/pages/contact.astro but visiting /contact shows a 404 error. What is the most likely cause?

medium

A. You forgot to restart the Astro dev server after adding the file.

B. The file is placed inside src/components instead of src/pages.

C. The file has a syntax error preventing Astro from loading it.

D. Astro requires a routing config to recognize new pages.

Solution

1. Step 1: Verify file placement

   The most likely cause is that the file is actually inside src/components instead of src/pages. Components folder files do not create routes.

2. Step 2: Syntax errors cause error pages, not 404

   Syntax errors show an error screen when visiting the route, not a 404 Page Not Found.

3. Step 3: Dev server auto-reloads

   Astro detects new pages automatically, restart rarely needed.

4. Final Answer:

   The file is placed inside src/components instead of src/pages. -> Option B

5. Quick Check:

   404 on new page = check pages vs components folder [OK]

Hint: New page 404s? Double-check src/pages vs components folder [OK]

Common Mistakes:

• Assuming routing config is needed
• Not checking file syntax
• Misplacing file in components folder

5. You want to create a nested page at URL /blog/post1. Which file structure and naming is correct in Astro?

hard

A. Create src/pages/blog/post1.astro file.

B. Create src/pages/blog-post1.astro file.

C. Create src/pages/blog/post1/index.html file.

D. Create src/pages/blog/post1.astro and add a routing config.

Solution

1. Step 1: Understand nested routing in Astro

   Folders inside src/pages create nested URL paths automatically.

2. Step 2: Map file to nested URL

   Placing post1.astro inside src/pages/blog creates URL /blog/post1.

3. Step 3: Check alternatives

   Create src/pages/blog-post1.astro file creates flat URL /blog-post1. Create src/pages/blog/post1/index.html file creates no route (.html not supported as pages). Create src/pages/blog/post1.astro and add a routing config is incorrect because Astro does not require routing config.

4. Final Answer:

   Create src/pages/blog/post1.astro file. -> Option A

5. Quick Check:

   Nested folder + file = nested URL [OK]

Hint: Nested folders in pages map to nested URLs directly [OK]

Common Mistakes:

• Using hyphens instead of folders for nesting
• Adding unnecessary routing config
• Confusing index.astro usage for nested pages