Appearance

Language

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.

Go deeper Choosing a Stack for a Personal Website: Astro + Cloudflare vs Next.js vs WordPress Why Astro, how it deploys to Cloudflare, and the real config files.

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 getCollection is a filter. Here it drops posts marked draft: true.
  • Always sort. The docs say the order getCollection returns 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:

ItemBeginner versionMy site
Where posts livesrc/content/blog/<slug>.mdsrc/content/posts/<slug>/<lang>.mdx
LoaderAstro'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 postsBuild your ownTimeline, stat cards, tables, callouts, sources, read-more cards
Draftsdraft: truedraft: 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. getCollection doesn’t guarantee order; sort for both the list and RSS.
  • Filtering drafts only on the list. Filter in getStaticPaths too, 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

  1. 1. Content collections · Astro · 2026-11-07
  2. 2. Install Astro · Astro · 2026-11-07
  3. 3. @astrojs/mdx · Astro · 2026-11-07
  4. 4. Add an RSS feed · Astro · 2026-11-07
  5. 5. Astro blog template · GitHub

About the author

Kelvin Wang

Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.

More about me