在 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" # remote 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 —— 每种都有各自的图标和配色。不少类型还支持别名（例如 HINT 和 IMPORTANT 等价于 TIP，CAUTION 等价于 WARNING）。完整说明见 rehype-callouts 文档。

可折叠的提示框

在类型后加 - 表示默认折叠，加 + 表示默认展开但可折叠：

自定义标题

在类型后面写上文字，就能把默认的类型标签替换成你想要的标题：

语法速查

> [!NOTE]
> 补充信息。

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

> [!TIP]+ 默认展开，但可折叠
> 一开始是打开的。

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

添加目录

默认情况下文章不带目录。想要目录的话，在你希望它出现的位置写一个 h2 标题（Markdown 中的 ##），内容为「目录」（英文 Table of contents 同样有效）：

---
# frontmatter
---

这里是在 AstroPaper 博客主题中新建文章的一些建议与技巧。

## 目录

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

标题层级

关于标题有一点需要注意：AstroPaper 会把 frontmatter 中的 title 作为文章的主标题，因此正文里的其余标题应当从 h2 ~ h6 中选用。

这不是硬性规定，但出于视觉呈现、无障碍访问和 SEO 的考虑，强烈建议遵守。

代码高亮

AstroPaper 默认使用 Shiki 做代码高亮，并配合 @shikijs/transformers 增强围栏代码块的能力。如果你不需要这些 transformer，可以移除：

npm remove @shikijs/transformers

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

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkToc, [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)

<!-- OR -->

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

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

放在 public/ 目录下

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

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

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

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

<!-- OR -->

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

附加建议

图片压缩

推荐的图片压缩站点：

• TinyPng
• TinyJPG

OG 图

文章没有指定 OG 图时会使用默认图。虽然不是必填，但仍建议在 frontmatter 中指定一张与文章内容相关的 OG 图。推荐尺寸为 1200 x 640 像素。