Build a personal website from 0
Add a Markdown Blog to an Astro Website (2026)
To add a blog to an Astro site you need a folder of Markdown files, one content collection config and two pages: a post list and a post page. No database. Full code, an RSS feed, and why my own site moved its posts out of a database and back into files.
Kelvin Wang · · 8 min read
Adding a blog to an Astro site takes four pieces: a folder of Markdown posts, a src/content.config.ts that tells Astro what a post looks like, a page that lists the posts, and a page that shows one post. No database and no admin panel. A new post is a new .md file; push it to GitHub, the site rebuilds, and the post is live. Every step has code you can paste, written against Astro’s current content collections API (checked against the official docs in November 2026) 1.
My site, kelvinwang.info, has 26 older posts in each of English and Chinese plus the new ones, and every one of them is a file in the repo. I took the long way round to get here; the last section explains why.
Before you start: an Astro site
If you don’t have a site yet, install Node.js (the docs ask for v22.23.4 or newer; odd-numbered releases such as v23 aren’t supported) 2 and run this in a terminal:
npm create astro@latest my-site
cd my-site
npm run dev
When the installer asks for a template, the minimal one is fine. Open http://localhost:4321 in your browser; if you see the home page, it worked.
If you’d rather skip the steps and start from a finished blog, Astro ships an official template: npm create astro@latest -- --template blog 5. It’s complete, but it has a lot of files, and a beginner can’t easily tell which file does what. Building it step by step means you’ll know where to look when you want to change something.
Step 1: Create the folder and your first post
Create a src/content/blog/ folder and add hello-world.md:
---
title: My first post
description: One or two sentences on what this post is about. Search results show this.
pubDate: 2026-11-07
tags: [notes]
---
This is the body. Some Markdown:
## A subheading
- Lists start with a dash
- **Bold** uses two asterisks
- [Links](https://example.com) use brackets then parentheses
The part between the two --- lines is the frontmatter: data about the post (title, summary, date). The body comes after it.
The file name becomes the URL: hello-world.md is served at /blog/hello-world/. Use lowercase words joined by hyphens, and don’t rename a file after it’s published. A new name is a new URL, and search results and links other people shared will break.
Step 2: The content collection config
Add content.config.ts inside src/:
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';
const blog = defineCollection({
// Read every .md and .mdx file under src/content/blog
loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
// Every post's frontmatter must match this; a missing or mistyped field fails the build
schema: z.object({
title: z.string(),
description: z.string(),
pubDate: z.coerce.date(),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
}),
});
export const collections = { blog };
The schema is the most useful part. Forget a description or write a date wrong, and npm run build fails and names the file, so a broken post never goes live quietly. That’s especially handy when an AI writes your posts, because it occasionally drops a field.
Step 3: The post list page
Add src/pages/blog/index.astro:
---
import { getCollection } from 'astro:content';
const posts = (await getCollection('blog', ({ data }) => !data.draft))
.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Blog</title>
</head>
<body>
<h1>Blog</h1>
<ul>
{posts.map((post) => (
<li>
<a href={`/blog/${post.id}/`}>{post.data.title}</a>
<time datetime={post.data.pubDate.toISOString()}>
{post.data.pubDate.toLocaleDateString('en-US')}
</time>
</li>
))}
</ul>
</body>
</html>
Two things to notice:
- The second argument to
getCollectionis a filter. Here it drops posts markeddraft: true. - Always sort. The docs say the order
getCollectionreturns isn’t guaranteed, so without a sort your posts can shuffle between builds.
Step 4: The post page
Add src/pages/blog/[id].astro. The square brackets make it a template that produces one page per post:
---
import { getCollection, render } from 'astro:content';
export async function getStaticPaths() {
const posts = await getCollection('blog', ({ data }) => !data.draft);
return posts.map((post) => ({
params: { id: post.id },
props: { post },
}));
}
const { post } = Astro.props;
const { Content } = await render(post);
---
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>{post.data.title}</title>
<meta name="description" content={post.data.description} />
</head>
<body>
<article>
<h1>{post.data.title}</h1>
<Content />
</article>
</body>
</html>
getStaticPaths runs once at build time and lists every page to generate. render(post) turns the Markdown into HTML, and <Content /> is the body. Filter drafts here too: if you only filter the list, a draft stays off the list but its URL still works.
Save, open http://localhost:4321/blog/, and you should see your first post’s title. Click it for the full post.
The <html> and <head> blocks repeat across both pages. If your site already has a shared layout, use it instead and pass in the title and description.
Step 5 (optional): Components inside posts with MDX
Plain Markdown covers text, images and tables. For interactive components or custom note boxes inside a post, switch to MDX 3:
npx astro add mdx
Create the component first. A minimal note box, src/components/Note.astro:
<aside style="border-left: 4px solid #888; padding: 0.5rem 1rem;">
<slot />
</aside>
<slot /> is where whatever you put between <Note> and </Note> ends up. Then rename a post to .mdx and import the component right below the frontmatter:
---
title: A post written in MDX
description: Posts can contain components.
pubDate: 2026-11-07
---
import Note from '../../components/Note.astro';
Regular Markdown text.
<Note>This is a custom note box.</Note>
The pattern in step 2 already includes .mdx, so the config doesn’t change.
Step 6 (optional): An RSS feed
RSS lets readers follow your posts in a feed reader. Set your site URL in astro.config.mjs (site: 'https://your-domain.com'), then install the official package 4:
npm install @astrojs/rss
Add src/pages/rss.xml.js:
import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';
export async function GET(context) {
const posts = await getCollection('blog', ({ data }) => !data.draft);
return rss({
title: 'My blog',
description: 'Posts from my personal website',
site: context.site,
items: posts.map((post) => ({
title: post.data.title,
pubDate: post.data.pubDate,
description: post.data.description,
link: `/blog/${post.id}/`,
})),
});
}
After a build, /rss.xml is your feed URL.
Step 7: Publish
When a post is ready:
git add src/content/blog/hello-world.md
git commit -m "post: hello world"
git push
If your host builds on push (Cloudflare Workers Builds, Vercel and Netlify can all be set up that way), the post is live a few minutes later. Otherwise rebuild and deploy the way you normally do.
Go deeper Cloudflare Workers Tutorial 2026: Astro SSR and Wrangler Deploy an Astro site to Cloudflare and have every push go live.Writing posts with AI
Because posts are files, an AI coding tool can create and edit them directly. I put one line in the project instructions file the AI tool reads (CLAUDE.md for Claude Code, AGENTS.md for Codex) saying where posts live and how files are named, so the AI always writes to the right folder. The schema catches posts with missing fields. My site also fails the build when an MDX post has no description, because without one the page would cut a search snippet from the raw MDX source, which can start with an import line.
Read every post before it goes out. Files make AI writing fast, and once pushed the post is public. My rule: drafting can be automatic; committing and pushing waits for my OK.
How my site does it (for experienced readers)
When I added a blog to my site on June 10, 2026, it was exactly the setup above: a glob() loader and one hello-world.mdx. The next day, June 11, I moved posts into a Supabase database, read at build time and published through an editor I wrote.
Five months later, on November 5, 2026, I moved them back into files, for two reasons:
- The editor stored HTML that could only hold paragraphs, headings, lists, tables and images. Posts that needed a timeline or stat cards, like an exchange incident page, were out of reach.
- I don’t edit posts in an admin editor. An AI drafts them, I read every one, and once I say it can go out, the AI handles the rest of publishing. The editor went unused, added limits, and kept a second copy of every post to sync.
The move exported all 52 published posts (26 per language) to files, then compared the site built before and after: 198 of 199 output files matched byte for byte. The one difference was a file-name hash in the admin app’s code.
The current setup has a few more layers than the beginner version, because the site has two languages and posts migrated from the database:
| Item | Beginner version | My site |
|---|---|---|
| Where posts live | src/content/blog/<slug>.md | src/content/posts/<slug>/<lang>.mdx |
| Loader | Astro's glob() | A custom loader that reads .mdx and the migrated .html files |
| URLs | /blog/<id>/ | /en/blog/<slug>/, /zh-hant/blog/<slug>/ |
| Components in posts | Build your own | Timeline, stat cards, tables, callouts, sources, read-more cards |
| Drafts | draft: true | draft: true, never read at build time |
If your site has one language, the beginner version will last you a long time.
Common mistakes
- Renaming a file breaks its URL. The URL comes from the file name. Add a redirect, or don’t rename.
- No sort.
getCollectiondoesn’t guarantee order; sort for both the list and RSS. - Filtering drafts only on the list. Filter in
getStaticPathstoo, or the draft’s URL still works. - Posts in subfolders.
glob()ids include the folder path (2026/hello). With a slash in the id, name the page[...id].astro. - Image paths. The simplest approach: put images in
public/images/and reference them as/images/xxx.webp.
Sources
Kelvin Wang
Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.
More about me