在 AstroPaper 主题中添加新文章

以下是在 AstroPaper 博客主题中创建新文章的一些规则/建议和技巧。

Table of contents

创建博客文章

要写新文章，在 src/data/blog/ 目录下创建一个 Markdown 文件。

AstroPaper v5.1.0 之前，所有文章必须在 src/data/blog/ 根目录下。自 v5.1.0 起，可以将文章按子目录组织，便于管理内容。

例如，想将文章按 2025 分组，可以放到 src/data/blog/2025/。这也会影响文章 URL：src/data/blog/2025/example-post.md 对应的 URL 是 /posts/2025/example-post。

如果不想子目录影响 URL，只需在文件夹名前加下划线 _。

# 示例：博客文章结构与 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 中覆盖文章的 slug。详见下一节。

如果构建产物中没有出现子目录 URL，删除 node_modules、重新安装依赖、重新构建即可。

Frontmatter

Frontmatter 是存储博客文章重要信息的主要位置，位于文章顶部，使用 YAML 格式。详见 Astro 文档。

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

示例：

author: Faris
pubDatetime: 2025-01-01T00:00:00Z
modDatetime: 2025-01-02T00:00:00Z
title: 示例文章标题
slug: example-post
featured: false
draft: false
tags:
  - astro
ogImage: ../../../assets/images/example.png # src/assets/images/example.png
description: 这是示例文章的描述。
canonicalURL: https://example.org/my-article-was-already-posted-here

添加目录

默认情况下文章不包含目录。要添加目录，需要在文章中以特定方式指定。

在你希望目录出现的位置，用 h2 格式写 Table of contents。

例如，如果想放在引言段落下方：

---
# frontmatter
---

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

## Table of contents

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

标题

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

此规则并非强制，但出于视觉、无障碍和 SEO 考虑强烈建议遵守。

语法高亮

AstroPaper 使用 Shiki 作为默认语法高亮。从 AstroPaper v5.4 开始，使用 @shikijs/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 中的图片。

注意！如果需要在 Markdown 中使用优化后的图片样式，应使用 MDX。

存放于 src/assets/（推荐）

图片放 src/assets/ 下，Astro 会通过 Image Service API 自动优化。

可使用相对路径或别名路径（@/assets/）：

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

<!-- 或者 -->

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

技术上说，图片可以放在 src 下任意目录，src/assets 只是建议。

存放于 public 目录

图片放 public 下不会被 Astro 处理，保持原始状态，需自行优化。应使用绝对路径：

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

<!-- 或者 -->

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

额外提示

图片压缩

放在博客文章中的图片（尤其是 public 目录下的）建议压缩，会影响网站整体性能。

推荐压缩工具：

• TinyPng
• TinyJPG

OG 图片

文章未指定 OG 图片时会使用默认 OG 图片。建议在 frontmatter 中指定与文章相关的 OG 图片，推荐尺寸 1200 X 640 px。

自 AstroPaper v1.4.0 起，未指定时会自动生成 OG 图片。详见公告。