在 AstroPaper 主题中添加新文章

本指南介绍在 AstroPaper 中创建新文章的规则与约定——文件位置、frontmatter 字段、图片以及语法高亮。

创建一篇博客文章

要写一篇新的博客文章，请在 src/content/posts/ 目录下创建一个 markdown（或 MDX）文件。

你可以用子目录来组织文章，让内容更容易管理。子目录名会成为文章 URL 的一部分。例如，src/content/posts/2025/example-post.md 会发布在 /posts/2025/example-post。

如果你只是想用子目录做整理、不希望它影响 URL，把文件夹名前加上下划线（_）前缀即可。

# 文章文件路径与对应 URL 的示例
src/content/posts/very-first-post.md          -> mysite.com/posts/very-first-post
src/content/posts/2025/example-post.md        -> mysite.com/posts/2025/example-post
src/content/posts/_2026/another-post.md       -> mysite.com/posts/another-post
src/content/posts/docs/_legacy/how-to.md      -> mysite.com/posts/docs/how-to
src/content/posts/Example Dir/Dummy Post.md   -> mysite.com/posts/example-dir/dummy-post

Frontmatter

Frontmatter 是存放博客文章元数据的主要位置。它位于文件顶部，采用 YAML 格式。更多关于 frontmatter 及其用法的内容，请阅读 Astro 文档。

以下是每篇文章可用的 frontmatter 属性列表：

frontmatter 中只有 title、description 和 pubDatetime 这三个字段必须填写。

标题和描述（摘要）对搜索引擎优化（SEO）很重要，因此 AstroPaper 建议你在所有博客文章中都填写它们。

如果某篇文章省略了 tags（也就是没有指定任何标签），那么该文章会使用默认标签 others。你可以在 src/content.config.ts 中设置默认标签：

// ...
tags: z.array(z.string()).default(["others"]), // 把 "others" 换成你想要的
// ...src/content.config.ts

Frontmatter 示例

下面是一份文章 frontmatter 的示例。

---
title: 文章标题
author: 你的名字
pubDatetime: 2022-09-21T05:17:19Z
featured: true
draft: false
tags:
  - some
  - example
  - tags
ogImage: ../../assets/images/example.png # src/assets/images/example.png
# ogImage: "https://example.org/remote-image.png" # 远程 URL
description: 这是示例文章的示例描述。
canonicalURL: https://example.org/my-article-was-already-posted-here
---src/content/posts/sample-post.md

VS Code 片段（可选）

AstroPaper 内置了工作区代码片段，可以加快创建新文章的速度：

• frontmatter：插入推荐的 frontmatter 块
• template：插入一个基础文章模板（包含 ## 目录）

这些片段位于 .vscode/astro-paper.code-snippets。如果你使用 VS Code（或 Cursor），打开工作区后它们应该会自动可用。

标注（Callouts）

从 AstroPaper v6.1 开始支持标注。它们使用由 rehype-callouts（Obsidian 主题）驱动的简单引用块语法。

以下是最常用的几种类型：

完整支持的类型包括：NOTE、ABSTRACT、INFO、TODO、TIP、SUCCESS、QUESTION、WARNING、FAILURE、DANGER、BUG、EXAMPLE、QUOTE——每种都有自己的图标和颜色。许多类型还支持别名（例如 TIP 对应 HINT 和 IMPORTANT，WARNING 对应 CAUTION）。完整参考请见 rehype-callouts 文档。

可折叠标注

在类型后加 - 可以让标注默认折叠，加 + 则让它默认展开但仍可折叠：

自定义标题

在类型后面加上任意文本，即可替换默认的类型标签：

语法速查

> [!NOTE]
> 补充信息。

> [!WARNING]- 默认折叠
> 展开前隐藏。

> [!TIP]+ 默认展开但可折叠
> 默认打开。

> [!DANGER] 自定义标题
> 替换默认标题。

添加目录

默认情况下，文章不包含任何目录（TOC）。要添加目录，写一个 目录 作为 h2 标题（Markdown 中的 ##），并放在你希望它出现的位置：

---
# frontmatter
---

这里放一些使用 AstroPaper 博客主题创建新文章的建议、技巧和经验。

## 目录

<!-- 文章的其余部分 -->

标题层级

标题层级有一点需要注意：AstroPaper 博客文章使用 frontmatter 中的 title 作为文章的主标题。因此文章中其余的标题应该使用 h2 ~ h6。

这条规则不是强制的，但出于视觉、无障碍和 SEO 的考虑，强烈建议遵守。

语法高亮

AstroPaper 默认使用 Shiki 作为语法高亮器，并使用 @shikijs/transformers 来增强代码块。如果你不想使用这些 transformer，可以把它们移除：

pnpm remove @shikijs/transformers

// ...
import {
  transformerNotationDiff,
  transformerNotationHighlight,
  transformerNotationWordHighlight,
} from "@shikijs/transformers";

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [
      [remarkToc, { heading: "(table[ -]of[ -])?contents?|toc|目录" }],
      [remarkCollapse, { test: "(table[ -]of[ -])?contents?|目录" }],
    ],
    shikiConfig: {
      themes: { light: "min-light", dark: "night-owl" },
      defaultColor: false,
      wrap: false,
      transformers: [
        transformerFileName(),
        transformerNotationHighlight(),
        transformerNotationWordHighlight(),
        transformerNotationDiff({ matchAlgorithm: "v3" }),
      ],
    },
  },
  // ...
});astro.config.ts

在博客内容中存放图片

有两种方法可以存放图片并在 markdown 文件中使用它们。

放在 src/assets/ 目录下（推荐）

你可以把图片存放在 src/assets/ 目录下。这些图片会被 Astro 通过 Image Service API 自动优化。

你可以用相对路径或别名路径（@/assets/）来引用它们。

举例：假设你想显示 example.jpg，它的路径是 src/assets/images/example.jpg。

![something](@/assets/images/example.jpg)

<!-- 或者 -->

![something](../../assets/images/example.jpg)

<!-- 在 markdown 里使用 img 标签或 Image 组件是无效的 ❌ -->
<img src="@/assets/images/example.jpg" alt="something">
<!-- ^^ 这样做是错的 -->

放在 public/ 目录下

你可以把图片存放在 public/ 目录下。请注意，存放在 public/ 中的图片不会被 Astro 处理，也就是说它们不会经过优化，图片优化需要你自己处理。

这类图片要用绝对路径引用。可以使用 markdown 图片语法或 HTML 的 img 标签来显示。

举例：假设 example.jpg 位于 public/assets/images/example.jpg。

![something](/assets/images/example.jpg)

<!-- 或者 -->

<img src="/assets/images/example.jpg" alt="something">

附加内容

图片压缩

推荐的图片压缩站点：

• TinyPng
• TinyJPG

OG 图片

如果文章没有指定 OG 图片，就会使用默认的 OG 图片。虽然不是必需的，但建议在 frontmatter 中指定一张与文章相关的 OG 图片。推荐的 OG 图片尺寸是 1200 X 640 px。