How to create a new page

Every page in src/pages/ becomes a page on your website. See the existing page such as index.mdx for reference.

How page names become URLs

Use lowercase filenames with hyphens, such as work-with-me.mdx.

Create an MDX page

Use MDX when your page is mostly text, headings, lists, images, and a few components.

Create src/pages/services.mdx:

---
layout: ../layouts/PageLayout.astro
title: Services
description: Learn about the services I offer.
---

import Button from "../components/Button.astro";

# Services

I help people create simple and useful websites.

## Website design

Add a short description of your service here.

<Button href="/contact">Contact me</Button>

You can now visit /services.

The beginning part between the --- lines is called frontmatter:

• layout adds the shared header, footer, page styles, and page information.
• title is the title shown in the browser and search results.
• description is a short summary of the page.
• topSpacing is optional. Set it to false when the page’s first component provides its own top spacing.

Imports go below the frontmatter and before the component is used.

Create a blog post

Regular pages go in src/pages/. Blog posts go in src/content/blog/.

Create a file such as src/content/blog/my-first-post.mdx:

---
title: My first post
description: A short introduction to my first blog post.
pubDate: 2026-08-01
---

## My first section

Write your post here.

The post will appear at /blog/my-first-post. Start blog post sections with ## because the blog layout already shows the post title as the main heading.

Keep blog post files directly inside src/content/blog/.

<Fragment slot="head">
    <meta name="category" content="events" />
</Fragment>

Before you publish

Check that:

1. The filename creates the URL you want.
2. The title and description explain the page clearly.
3. The page has one main # or <h1> heading.
4. Links do not end with a slash.
5. The page is in the menu if visitors need it there.
6. Images have useful alternative text.