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

原文章：Adding new posts in AstroPaper theme

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

Free Classic wooden desk with writing materials, vintage clock, and a leather bag. Stock Photo — Photo by Pixabay

Open Table of contents

创建博客帖子
Frontmatter
- 示例 Frontmatter
添加目录
标题
语法高亮
存储博客内容的图像
- 在 src/assets/ 目录中（推荐）
- 在 public 目录中
额外内容
- 图像压缩
- OG 图像

创建博客帖子

要撰写新博客帖子，请在 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属性列表。

属性	描述	备注
*title*	帖子的标题. (h1)	required^*
*description*	帖子的描述，用于帖子摘录和网站描述	required^*
*pubDatetime*	以ISO 8601格式发布的日期时间	required^*
*modDatetime*	以ISO 8601格式修改的日期时间（仅在修改博客帖子时添加此属性）	optional
*author*	帖子的作者	default = SITE.author
*slug*	帖子的别名，此字段是可选的	default = slugified file name
*featured*	是否在主页的特色部分显示此帖子	default = false
*draft*	将此帖子标记为 “未发布”	default = false
*tags*	此帖子的相关关键字，以数组 yaml 格式书写	default = others
*ogImage*	帖子的OG图像，对社交媒体分享和SEO很有用，可以是远程URL或相对于当前文件夹的图像路径	default = `SITE.ogImage` or generated OG image
*canonicalURL*	规范URL（绝对），以防文章已存在于其他来源	default = `Astro.site` + `Astro.url.pathname`
*hideEditPost*	隐藏博客标题下的编辑帖子按钮，这仅适用于当前博客帖子。	default = false
*timezone*	为当前博客帖子指定IANA格式的时区，这将覆盖当前博客帖子的 `SITE.timezone` 配置	default = `SITE.timezone`

提示：您可以通过在控制台运行 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

添加目录

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

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

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

---
# frontmatter
---

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

## Table of contents

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

标题

关于标题有一点需要注意。AstroPaper 博客帖子使用标题（Frontmatter中的标题）作为帖子的主标题。因此，帖子中的其他标题应使用 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/ 目录中。这些图像将通过 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` 目录中

您可以将图像存储在 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 目录下的图像），建议对图像进行压缩。这将影响网站的整体性能。

我推荐的图像压缩网站。

OG 图像

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

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

（完）

如果这篇文章刚好帮到了你，欢迎请我喝杯咖啡！