在AstroPaper主题中添加新帖子（译）

原文章：Adding new posts in AstroPaper theme

以下是一些在 AstroPaper 博客主题中创建新帖子的规则/建议、技巧和窍门。

Table of contents

创建博客帖子

要撰写新博客帖子，请在 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，只需在文件夹名称前加上一个下划线 _。

# 示例：博客帖子结构和URLs
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 中覆盖博客帖子的别名。有关更多细节，请参见下一部分。

如果子目录URL未出现在构建输出中，请删除 node_modules，重新安装软件包，然后重新构建。

Frontmatter

Frontmatter是存储博客帖子（文章）一些重要信息的主要地方。Frontmatter位于文章顶部，并以YAML格式编写。有关Frontmatter及其用法的更多信息，请参阅Astro文档。

以下是每个帖子的Frontmatter属性列表。

提示：您可以通过在控制台运行 new Date().toISOString() 来获取 ISO 8601 日期时间。确保删除引号。

Frontmatter 中仅需指定 title、description 和 pubDatetime 字段

标题和描述（摘录）对搜索引擎优化（SEO）很重要，因此 AstroPaper 鼓励在博客帖子中包含这些内容。

slug 是 URL 的唯一标识符。因此，slug 必须唯一并且与其他帖子不同。 slug 的空格应使用 - 或 _ 分隔，但推荐使用 -。slug 是通过博客帖子文件名自动生成的。不过，您可以在博客帖子中将 slug 定义为 Frontmatter。

例如，如果博客文件名是 adding-new-post.md 并且您未在 Frontmatter 中指定 slug，Astro 将使用文件名自动为博客帖子创建 slug。因此，slug 将是 adding-new-post。但是如果您在Frontmatter 中指定了 slug，这将覆盖默认的 slug。有关更多信息，请参阅 Astro文档。

如果您在博客帖子中省略 tags（换句话说，如果未指定任何标签），则默认标签 others 将用作该帖子的标签。您可以在 content.config.ts 文件中设置默认标签。

export const blogSchema = z.object({
  // ...
  draft: z.boolean().optional(),
  tags: z.array(z.string()).default(["others"]), // 将 "others" 替换为您想要的任何内容
  // ...
});src/content.config.ts

示例 Frontmatter

以下是帖子的示例 Frontmatter 。

---
title: The title of the post
author: your name
pubDatetime: 2022-09-21T05:17:19Z
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" # remote URL
description: 这是示例帖子的示例描述。
canonicalURL: https://example.org/my-article-was-already-posted-here
---src/data/blog/sample-post.md

添加目录

By default, a post (article) does not include any table of contents (toc). To include toc, you have to specify it in a specific way.

Write Table of contents in h2 format (## in markdown) and place it where you want it to be appeared on the post.

For instance, if you want to place your table of contents just under the intro paragraph (like I usually do), you can do that in the following way.

默认情况下，帖子（文章）不包括任何目录（toc）。要包含 toc，您必须以特定方式指定它。

以 h2 格式（markdown中为##）写下 Table of contents，并将其放置在您希望出现在帖子的地方。

例如，如果您想将目录放在介绍段落下方（就像我通常做的那样），您可以这样做。

---
# frontmatter
---

以下是一些建议、技巧和窍门，用于在AstroPaper博客主题中创建新帖子。

## Table of contents

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

标题

关于标题有一点需要注意。AstroPaper 博客帖子使用标题（Frontmatter中的标题）作为帖子的主标题。因此，帖子中的其他标题应使用 h2 ~ h6。

此规则不是强制性的，但出于可视化、可访问性和SEO目的，强烈建议遵循。

语法高亮

AstroPaper uses Shiki as the default syntax highlighting. Starting from AstroPaper v5.4, @shikijs/transformers is used to enhance better fenced code blocks. If you don’t want to use it, you can simply remove it like this

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/ 目录中（推荐）

You can store images inside src/assets/ directory. These images will be automatically optimized by Astro through Image Service API.

You can use relative path or alias path (@/assets/) to serve these images.

Example: Suppose you want to display example.jpg whose path is /src/assets/images/example.jpg.

您可以将图像存储在 src/assets/ 目录中。这些图像将通过 Image Service API 被 Astro 自动优化。

您可以使用相对路径或别名路径（@/assets/）来提供这些图像。

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

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

<!-- OR -->

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

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

从技术上讲，您可以在 src 下的任何目录中存储图像。在这里，src/assets 只是一个建议

在 public 目录中

You can store images inside the public directory. Keep in mind that images stored in the public directory remain untouched by Astro, meaning they will be unoptimized and you need to handle image optimization by yourself.

For these images, you should use an absolute path; and these images can be displayed using markdown annotation or HTML img tag.

Example: Assume example.jpg is located at /public/assets/images/example.jpg.

您可以将图像存储在 public 目录中。请记住，存储在 public 目录中的图像不会被 Astro 处理，这意味着它们将不会被优化，您需要自己处理图像优化。

对于这些图像，您应使用绝对路径，这些图像可以使用 markdown annotation 或 HTML img tag 显示。

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

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

<!-- OR -->

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

额外内容

图像压缩

当您在博客帖子中放置图像时（尤其是 public 目录下的图像），建议对图像进行压缩。这将影响网站的整体性能。

我推荐的图像压缩网站。

• TinyPng
• TinyJPG

OG 图像

如果帖子未指定OG图像，将放置默认OG图像。虽然不是必需的，但与帖子相关的OG图像应在前matter中指定。推荐的OG图像尺寸为 1200 X 640 像素。

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