Migrating From Wagtail To Astro (3): Adding New Posts
Migrating From Wagtail To Astro (3): Adding New Posts
This is the third article in the Wagtail-to-Astro series. It explains how to add a new post after the migration, including category, tags, column, hero image, and homepage recommendation behavior.
Where Posts Live
All posts live under an Astro Content Collection. In this site, the relevant directories are:
- Historical imports:
src/content/blog/imported/*.md - New posts: they can continue living under
imported/, or use a separate directory such assrc/content/blog/posts/, as long as the collection glob matches**/*.md.
For new posts, use meaningful file names such as wagtail-to-astro-3-new-posts.md, so the file name and slug are easy to match. If content.config.ts uses glob() to include **/*.md, Markdown files under any subdirectory will be collected. You can organize by year or column, such as blog/2025/ or blog/wagtail-migration/, to keep the repository tidy.
Required And Common Frontmatter
Each Markdown file starts with YAML frontmatter. Astro validates it using the schema in content.config.ts.
Required Fields
title: "Post title"
description: "Short summary for lists and SEO"
pubDate: "2025-03-15"
slug: "url-slug"
draft: false- slug: Used to generate the URL, such as
/blog/<slug>/. English or pinyin slugs are usually easier to maintain than strings with special characters. - draft: true: The post will not appear in normal published lists. This is useful for unfinished drafts.
Optional But Common Fields
updatedDate: "2025-03-15"
category: "Blogging"
column: "Wagtail To Astro"
authors:
- "Alex Xiang"
tags:
- "astro"
- "markdown"
heroImage: "https://picsum.photos/seed/xxx/800/420"- category: The main category used by the site navigation.
- column: A column or series name. This migration series uses the same column.
- tags: A string array used by tag pages and site search.
- heroImage: A remote URL or local path such as
/uploads/xxx.jpg. Posts with hero images can be used in homepage recommendation sections.
Write The Body In Markdown
Below the frontmatter, write normal Markdown. Headings, lists, code blocks, quotes, links, and images are supported:
## Section Title
Body text with **bold**, *italic*, and [links](https://example.com).
- Item 1
- Item 2
\`\`\`bash
echo "code block"
\`\`\`For local images, use paths starting with /uploads/, corresponding to files under public/uploads/. Astro copies files under public/ into dist/ as-is, so /uploads/xxx.jpg at runtime maps to dist/uploads/xxx.jpg.
If you want responsive images or lazy loading, you can wrap images with Astro’s <Image> component in the layout. For simple posts, normal Markdown image syntax is enough.
How Homepage Recommendations Work
The homepage recommendation section is based on non-draft posts with heroImage, sorted by publication date. Therefore:
- As long as frontmatter includes heroImage, the new post enters the recommendation pool.
- For good hero images, use a reliable remote image, or place an image under
public/uploads/and use a local path.
Next Article
After writing a new post, check these items: pnpm build passes, the post appears at /blog/<slug>/, category/tag/column pages list the post correctly, and if heroImage is set, the post can appear in homepage recommendations.
Series: Part 1: Why migrate and how I chose · Part 2: The main phases · Part 3: Adding new posts · Part 4: Deployment · Part 5: Data sync and scripting · Part 6: Theme and feature polish
Follow ZiCode on WeChat
If this post was useful, you can follow later updates on WeChat as well.
X / Twitter
Follow @ax2_zicode
Faster technical notes, short thoughts, and new-post alerts are posted on X.
