从 Wagtail 迁移到 Astro（三）：添加新文章

作者: Alex Xiang

本文是「Wagtail 迁移 Astro」系列的第三篇，说明在迁移完成后的 Astro 项目中，如何添加一篇新文章，并让它带上分类、标签、专栏和头图，还能在首页推荐位展示。

一、文章放在哪里

本站文章统一放在 Content Collection 下，对应目录：

历史导入：src/content/blog/imported/*.md
新文章：可以继续放在 imported/，或单独建子目录如 src/content/blog/posts/，只要匹配 **/*.md 即可被收集。

建议新文章使用有意义的文件名，例如：wagtail-to-astro-3-new-posts.md，便于和 slug 对应。若使用 content.config.ts 的 glob() 只匹配 **/*.md，则任意子目录下的 .md 都会被收入，可按年份或专栏建子目录（如 blog/2025/、blog/wagtail-migration/）以保持整洁。

二、Frontmatter 必填与可选

每篇 Markdown 顶部用 YAML 写 frontmatter，Astro 会按 content.config.ts 里的 schema 校验。推荐字段如下。

2.1 必填

title: "文章标题"
description: "简短摘要，用于列表和 SEO"
pubDate: "2025-03-15"
slug: "url-slug"
draft: false

slug：用于生成 URL，如 /blog/<slug>/，建议英文或拼音，避免特殊字符。
draft: true 时不会在 getCollection 的默认列表中出现，适合写了一半先不发布。

2.2 可选但常用

updatedDate: "2025-03-15"
category: "博客"
column: "Wagtail迁移Astro"
authors:
  - "Alex Xiang"
tags:
  - "astro"
  - "markdown"
heroImage: "https://picsum.photos/seed/xxx/800/420"

category：分类，与站内「分类」导航一致。
column：专栏，本系列可统一为「Wagtail迁移Astro」。
tags：标签数组，用于标签页与站内搜索。
heroImage：头图 URL 或站内路径（如 /uploads/xxx.jpg），有头图的文章可优先出现在首页推荐位。

三、正文用 Markdown 写

frontmatter 下方直接写 Markdown 即可，支持标题、列表、代码块、引用、图片等。例如：

## 小节标题

正文内容，**加粗**、*斜体*、[链接](https://example.com)。

- 列表项 1
- 列表项 2

\`\`\`bash
echo "代码块"
\`\`\`

图片若用站内资源，路径建议以 /uploads/ 开头，对应 public/uploads/ 下的文件。构建时 Astro 会把 public/ 下的内容原样拷贝到 dist/，因此 /uploads/xxx.jpg 在运行时即对应 dist/uploads/xxx.jpg。

小技巧：若希望正文里的图片支持响应式或懒加载，可在布局里用 Astro 的 <Image> 组件包装；若只是简单 ![](path)，保持 Markdown 写法即可。

四、首页推荐位是怎么来的

本站首页「推荐文章」区块取自：有 heroImage 且非 draft 的文章，按发布时间取前若干篇。因此：

只要在 frontmatter 里加上 heroImage（可以是外链图或本地路径），新文章就会进入推荐池。
若希望头图好看，可使用 Unsplash/Pexels 等图床，或把图片放到 public/uploads/ 后写相对路径。

五、本系列的下一篇

检查清单：写完新文章后，可依次确认：pnpm build 无报错、文章出现在 /blog/<slug>/、分类/标签/专栏页能正确列出该文、若设置了 heroImage 则首页推荐位能看到。

本系列文章：（一）为什么迁移与选型 · （二）迁移的几个阶段 · （三）添加新文章（本文） · （四）上线 · （五）数据同步与脚本化 · （六）主题与功能打磨