Writing Blog Posts with MDX

Every blog post is an .mdx file inside src/data/blog/. MDX is Markdown with the ability to import and use Astro (or React) components directly in your prose. You get the simplicity of Markdown with the flexibility of components when you need them.

Creating a new post

The fastest way is the admin panel at http://localhost:4321/admin/. Click + New, enter a title, and the slug is auto-generated. You’ll land straight in the editor.

Alternatively, create a file manually:

touch src/data/blog/my-new-post.mdx

Frontmatter

Every post starts with a YAML frontmatter block between --- delimiters:

---
title: My Post Title
description: One or two sentences shown in search results and post cards.
pubDate: 2026-04-24
updatedDate: 2026-05-01
author: Jane Doe
tags:
  - tutorial
  - web
heroImage: /images/blog/my-post/hero.webp
draft: false
featured: false
---

Markdown basics

Standard CommonMark markdown works everywhere:

## Heading level 2

Regular paragraph with **bold**, _italic_, and `inline code`.

- Bullet list
- Another item

1. Numbered list
2. Second item

> Blockquote for longer citations.

[Link text](https://example.com)

![Image alt text](/images/my-image.png)

Code blocks

Wrap code in triple backticks with a language identifier. Syntax highlighting is handled by Expressive Code with a Shiki backend:

```ts
function greet(name: string): string {
  return `Hello, ${name}`;
}
```

Supported features: line numbers, diff highlighting, titles, and more — see the Expressive Code docs.

Importing custom components

After the frontmatter, import any component you want to use:

import Callout from "@/components/blog/Callout.astro";
import Steps from "@/components/blog/Steps.astro";

<Callout type="success" title="Works!">
  This is a custom component inside MDX.
</Callout>

All available components are documented in the Component Reference post.

Images

Put images in public/images/blog/your-slug/ and reference them with a root-relative path:

import Figure from "@/components/blog/Figure.astro";

<Figure
  src="/images/blog/my-post/screenshot.webp"
  alt="Descriptive alt text"
  caption="Optional caption shown below the image."
/>

Keyboard shortcuts in the editor

When writing in the admin panel:

• ⌘ + S — save (autosave also runs after 900ms of inactivity)
• Switch to the Frontmatter tab to edit metadata without touching YAML by hand
• The Components tab in the right panel shows a searchable list with insert snippets
• The Images tab lets you upload and copy image URLs directly

Drafts and scheduling

Set draft: true to hide a post from production. It still appears in the admin panel and in bun run dev.

To schedule a post, set pubDate to a future date — it will be hidden until that date is reached (within the grace window configured in site.config.ts).

Tags

Tags are free-form strings. They generate tag pages at /tags/your-tag/ automatically. Use consistent, lowercase, hyphenated slugs:

tags:
  - web-development
  - typescript
  - tutorial

Frontmatter tips