在 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 格式。你可以在 Astro 文档中进一步了解 frontmatter 及其用法。

下面是每篇文章可用的 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:
  - 示例
  - 标签
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 开始支持 callout 提示块。它们使用一种简单的 blockquote 语法，并由 rehype-callouts（Obsidian 主题）提供支持。

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

完整支持的类型包括：NOTE、ABSTRACT、INFO、TODO、TIP、SUCCESS、QUESTION、WARNING、FAILURE、DANGER、BUG、EXAMPLE、QUOTE。每种类型都有自己的图标和颜色。许多类型也支持别名，例如 HINT 和 IMPORTANT 可作为 TIP 使用，CAUTION 可作为 WARNING 使用。完整参考请查看 rehype-callouts 文档。

可折叠提示块

在类型后加 - 可以让提示块默认折叠；加 + 可以让提示块默认展开，但仍然可以折叠：

自定义标题

如果你想替换默认的类型标签，可以在类型后添加任意标题：

语法速览

> [!NOTE]
> 补充信息。

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

> [!TIP]+ 默认展开，但可以折叠
> 初始状态为打开。

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

添加目录

默认情况下，文章不会包含目录（TOC）。如果要添加目录，请把 目录 写成 h2 标题（Markdown 中的 ##），并放在你希望目录出现的位置：

---
# frontmatter
---

这里是一些在 AstroPaper 博客主题中创建新文章时可参考的建议、技巧和注意事项。

## 目录

<!-- 文章的其余内容 -->

标题层级

关于标题有一点需要注意。AstroPaper 会把 frontmatter 中的 title 作为文章的主标题。因此，正文中的其它标题应该从 h2 到 h6 开始使用。

这条规则不是强制性的，但从视觉层级、可访问性和 SEO 的角度来看都强烈推荐。

语法高亮

AstroPaper 默认使用 Shiki 作为语法高亮工具，并通过 @shikijs/transformers 增强 fenced code block。如果你不想使用这些 transformers，可以将它们移除：

pnpm remove @shikijs/transformers

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

const tocHeading = "目录|(table[ -]of[ -])?contents?|toc";
const tocHeadingPattern = /^(目录|(table[ -]of[ -])?contents?|toc)$/i;

export default defineConfig({
  // ...
  markdown: {
    processor: unified({
      remarkPlugins: [
        [remarkToc, { heading: tocHeading }],
        [remarkCollapse, { test: tocHeadingPattern }],
      ],
    }),
    shikiConfig: {
      themes: { light: "min-light", dark: "min-dark" },
      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 图片。虽然 OG 图片不是必填项，但建议在 frontmatter 中指定一张与文章相关的 OG 图片。推荐的 OG 图片尺寸是 1200 X 640 px。