Skip to main content
Blog posts are the core of your content strategy. They’re stored in src/content/blog/ as markdown files with frontmatter defining metadata.

​
Blog Collection Schema

The blog collection is defined in src/content.config.ts with the following schema:
​
title
string
required
The title of your blog post. This appears as the main heading and in meta tags.
​
author
string
required
The author’s name (e.g., “Lewis Kori”)
​
tags
array
required
An array of tag strings for categorization (e.g., ["Writing", "Learning", "Clarity"])
​
description
string
required
A brief summary of the post. Used for SEO meta descriptions and post previews.
​
dateCreated
date
required
Publication date in YYYY-MM-DD format (e.g., 2025-09-16)
​
cover_image
string
Optional path to a cover image for the post (e.g., /blog/my-post-cover.jpg)
​
series
string
Optional series name to group related posts together (e.g., "Human + AI")
​
sponsors
array
Optional array of sponsor names (e.g., ["Scraper API"])
​
canonical_url
string (URL)
Optional canonical URL if the post was originally published elsewhere

​
Creating a New Blog Post

1

Create a new markdown file

Navigate to src/content/blog/ and create a new .md file. Use kebab-case for the filename:
touch src/content/blog/my-new-post.md
2

Add frontmatter

Start your file with YAML frontmatter containing all required fields:
---
title: Why I Write
author: Lewis Kori
tags: ["Writing", "Learning", "Clarity", "Teaching", "Expression", "Growth"]
description: Writing helps me think clearly, learn better and communicate with intention. It is a way to teach, connect with strangers, grow in my career and let loose ideas that deserve to be shared.
dateCreated: 2025-09-16
sponsors: []
---
3

Write your content

Below the frontmatter, write your post content using markdown:
I've been thinking lately about why I write. Not in the mechanical sense 
of sitting down with a blank page and stringing words together, but the 
deeper reason why I keep showing up to it.

## The Power of Clarity

For me, writing is not just about publishing a blog post, an essay or a 
reflection. It's about clarity...
4

Preview and publish

Run your development server to preview the post:
npm run dev
The post will be automatically available at /blog/my-new-post

​
Working with Series

Series allow you to group related blog posts together. When you add a series field to your frontmatter, posts with the same series name will be linked together.

​
Example: Creating a Series

---
title: AI Is Not Replacing You. It's Reshaping How You Think.
author: Lewis Kori
tags: ["artificial intelligence", "software engineering", "ai agents"]
series: Human + AI
description: A software engineer reflects on how AI agents are reshaping engineering work
dateCreated: 2026-02-17
sponsors: ["Scraper API"]
---
All posts with series: Human + AI will be automatically grouped and can be displayed together on your site.

​
Adding Sponsors

If your blog post is sponsored, you can list sponsors in the frontmatter: 
---
title: My Sponsored Post
author: Lewis Kori
tags: ["tutorial"]
description: A helpful tutorial
dateCreated: 2025-03-15
sponsors: ["Scraper API", "Company Name"]
---
You can also use an empty array if there are no sponsors: 
sponsors: []

​
Real-World Examples

---
title: Why I Write
author: Lewis Kori
tags: ["Writing", "Learning", "Clarity", "Teaching", "Expression", "Growth"]
description: Writing helps me think clearly, learn better and communicate with intention.
dateCreated: 2025-09-16
sponsors: []
---

I've been thinking lately about why I write. Not in the mechanical sense of 
sitting down with a blank page and stringing words together, but the deeper 
reason why I keep showing up to it.

For me, writing is not just about publishing a blog post, an essay or a 
reflection. It's about clarity. Thoughts tend to be messy when they live 
only in the mind...

---
title: AI Is Not Replacing You. It's Reshaping How You Think.
author: Lewis Kori
tags: ["artificial intelligence", "software engineering", "ai agents", "future of work"]
series: Human + AI
description: A software engineer reflects on how AI agents are reshaping engineering work, job expectations, and the definition of leverage.
dateCreated: 2026-02-17
sponsors: ["Scraper API"]
---

When AI started writing decent code, I did not feel excitement.

I felt unsettled.

Part of it was personal. I had built a career on being able to untangle 
complex systems, reason through architectural tradeoffs, and hold messy 
abstractions in my head until they became clear...

​
File Organization

Blog posts are stored in src/content/blog/ with the following structure: 
src/content/blog/
├── why-i-write.md
├── ai-is-not-replacing-you-its-reshaping-how-you-think.md
├── building-web-apis-with-django.md
└── ...
The filename becomes the URL slug. For example, why-i-write.md will be accessible at /blog/why-i-write

​
Best Practices

  1. Use descriptive filenames - Keep them concise but descriptive, using kebab-case
  2. Write clear descriptions - Your description is used for SEO and social media previews
  3. Tag strategically - Use 3-6 relevant tags that help categorize your content
  4. Set accurate dates - The dateCreated field determines post ordering
  5. Optimize images - If using cover_image, ensure images are optimized for web
  6. Group with series - Use series to create cohesive content collections

​
Querying Blog Posts

In your Astro components, you can query blog posts using the Content Collections API: 
import { getCollection } from 'astro:content';

// Get all blog posts
const allPosts = await getCollection('blog');

// Get posts sorted by date
const sortedPosts = allPosts.sort(
  (a, b) => b.data.dateCreated.valueOf() - a.data.dateCreated.valueOf()
);

// Get posts in a specific series
const seriesPosts = allPosts.filter(
  post => post.data.series === 'Human + AI'
);

Build docs developers (and LLMs) love

Get started for freeTalk to us