在 AstroPaper 中新增文章

这篇文章整理了在 AstroPaper 中创建新文章时最常用的实践，帮助你用更稳定的方式组织内容、管理链接和维护 frontmatter。

创建文章文件

在 src/data/blog/ 目录中创建 Markdown 文件即可。

从 AstroPaper v5.1.0 开始，你可以把文章放到子目录中。例如：

src/data/blog/2025/example-post.md -> /posts/2025/example-post
src/data/blog/_2026/another-post.md -> /posts/another-post

如果你不希望子目录影响 URL，请在目录名前加下划线。

src/data/blog/very-first-post.md          -> mysite.com/posts/very-first-post
src/data/blog/2025/example-post.md        -> mysite.com/posts/2025/example-post
src/data/blog/_2026/another-post.md       -> mysite.com/posts/another-post
src/data/blog/docs/_legacy/how-to.md      -> mysite.com/posts/docs/how-to
src/data/blog/Example Dir/Dummy Post.md   -> mysite.com/posts/example-dir/dummy-post

Frontmatter 关键字段

每篇文章都建议包含以下字段：

title：文章标题（必填）
description：摘要描述（必填）
pubDatetime：发布时间（必填）
modDatetime：修改时间（可选）
slug：自定义链接标识（可选）
featured：是否出现在首页精选
draft：是否草稿
tags：标签数组
ogImage：社交分享图
canonicalURL：规范链接

仅 title、description、pubDatetime 是强制要求。其余字段可按需求补充。

slug 与文件名关系

若不写 slug，系统会根据文件名自动生成。

例如文件名为 adding-new-post.md，则默认 slug 是 adding-new-post。若在 frontmatter 中写了 slug，会覆盖默认值。

默认标签

如果文章未填写 tags，默认会使用 others（可在内容配置里改成你自己的默认标签）。

目录（TOC）写法

如果你想显示目录，需要在正文里写一个二级标题：

## Table of contents

目录会在该位置展开。

标题层级建议

页面主标题已经由 frontmatter 的 title 提供，因此正文建议从 h2 开始（即 ##）。这样在可访问性与 SEO 上更规范。

代码高亮

AstroPaper 默认使用 Shiki，并支持更强的代码块增强能力。如果你不需要 transformers，可移除对应依赖与配置。

图片存放建议

推荐把图片放在 src/assets 下，Astro 会自动优化。若放 public 目录，则需要自行处理压缩和优化。

总结

建立稳定的 frontmatter 规范、合理使用 slug 和目录结构，是长期维护博客的关键。先把规则定好，后续写作会顺畅很多。