Adding new posts in AstroPaper theme

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

目录

创建博客文章

要编写新的博客文章，请在 src/data/blog/ 目录下创建一个 markdown 文件。

在 AstroPaper v5.1.0 之前，所有博客文章都必须存放在 src/data/blog/ 中，这意味着你无法将它们组织到子目录中。

从 AstroPaper v5.1.0 开始，你现在可以将博客文章组织到子目录中，从而更方便地管理内容。

例如，如果你想将文章归类到 2025 下，可以将它们放在 src/data/blog/2025/ 中。这也会影响文章的 URL，因此 src/data/blog/2025/example-post.md 将通过 /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 是存储博客文章（文章）重要信息的主要位置。Frontmatter 位于文章顶部，采用 YAML 格式编写。更多关于 frontmatter 及其用法的信息，请参阅 Astro 文档。

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

* 表示 title、description、pubDatetime 和 author 属性在 post（文章）中是必需的。

** 表示属性是可选的，但你仍然应该指定它们以获得更好的体验。

*** 表示 [autogenerated] 属性仅在生成模式为静态（output: "static"）时有效。

提示：你可以在 src/config.ts 中为 tag 属性设置默认值。 （阅读：博客设置）

以下是一个示例 frontmatter：

# src/data/blog/some-post/some-post.md
author: 你的名字
pubDatetime: 2022-09-23T15:22:00Z
modDatetime: 2025-01-16T15:22:00Z
title: 文章的标题
slug: the-title-of-the-post
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

添加目录

默认情况下，文章不包含任何目录（table of contents，简称 toc）。要包含目录，你需要以特定方式指定它。

以 h2 格式（markdown 中的 ##）编写 目录，并将其放在你希望它出现在文章中的位置。

例如，如果你想将目录放在引言段落的正下方（就像我通常做的那样），你可以按以下方式操作。

---
# frontmatter
---

以下是在 AstroPaper 博客主题中创建新文章的一些建议、提示与技巧。

## 目录

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

标题

关于标题有一点需要注意。AstroPaper 博客文章使用标题（frontmatter 中的 title）作为文章的主标题。因此，文章中的其余标题应使用 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: {
      // 更多主题请访问 https://shiki.style/themes
      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/）来引用这些图片。

示例：假设你想显示图片 example.jpg，其路径为 /src/assets/images/example.jpg。

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

<!-- 或 -->

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

<!-- 使用 img 标签或 Image 组件将不起作用 ❌ -->
<img src="@/assets/images/example.jpg" alt="something">
<!-- ^^ 这是错误的 -->

技术上来说，你可以将图片存储在 src 下的任何目录中。这里 src/assets 只是一个推荐。

存放在 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">

额外建议

图片压缩

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

我推荐的图片压缩站点：

• TinyPng
• TinyJPG

OG 图片

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

自 AstroPaper v1.4.0 起，如果未指定 OG 图片，将自动生成。查看公告。