【转载】AstroPaper 主题中新增博客文章

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

目录

创建博客文章

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

你可以将文章归入子目录，以便更轻松地管理内容。子目录名称会成为文章 URL 的一部分。例如，src/content/posts/2025/example-post.md 将通过 /posts/2025/example-post 访问。

如果你只想用子目录来组织内容、又不想让它影响 URL，可以在文件夹名称前加下划线（_）。

# Example: post file paths and their URLs
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"]), // replace "others" with whatever you want
// ...src/content.config.ts

示例 Frontmatter

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

---
title: The title of the post
author: your name
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: This is the example description of the example post.
canonicalURL: https://example.org/my-article-was-already-posted-here
---src/content/posts/sample-post.md

VS Code 代码片段（可选）

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

• frontmatter：插入推荐的 frontmatter 块
• template：插入基础文章模板（包含 ## Table of contents）

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

提示框（Callouts）

AstroPaper 从 v6.1 版本开始支持提示框（callouts）。它们采用由 rehype-callouts（Obsidian 主题）提供的简洁 blockquote 语法。

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

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

可折叠提示框

在类型后加上 - 可使提示框默认折叠，加上 + 则可使其默认展开但可折叠：

自定义标题

在类型后添加文字，即可用任意标题替换默认的类型标签：

语法摘要

> [!NOTE]
> Supplementary information.

> [!WARNING]- Collapsed by default
> Hidden until expanded.

> [!TIP]+ Expanded, but collapsible
> Starts open.

> [!DANGER] Custom title
> Replaces the default heading.

添加目录

默认情况下，文章不会包含目录（TOC）。若要添加，请将 Table of contents 写为 h2 标题（Markdown 中的 ##），并放在你希望它出现的位置：

---
# frontmatter
---

Here are some recommendations, tips & tricks for creating new posts in AstroPaper blog theme.

## Table of contents

<!-- the rest of the post -->

标题

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

这条规则并非强制，但出于视觉、可访问性（accessibility）和 SEO 方面的考虑，强烈推荐遵循。

语法高亮

AstroPaper 使用 Shiki 作为默认语法高亮工具，并通过 @shikijs/transformers 增强围栏代码块的功能。如果你不想使用这些 transformers，可以将其移除：

pnpm 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/）来引用这些图片。

示例：假设你想展示路径为 src/assets/images/example.jpg 的 example.jpg。

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

<!-- OR -->

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

<!-- Using img tag or Image component won't work in markdown ❌ -->
<img src="@/assets/images/example.jpg" alt="something">
<!-- ^^ This is wrong -->

存放在 public/ 目录中

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

对于这些图片，请使用绝对路径。可以使用 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 图片，将使用默认的 OG 图片。尽管并非必填，但建议在 frontmatter 中指定一张与文章相关的 OG 图片。OG 图片的推荐尺寸为 1200 X 640 像素。