如何在 AstroPaper 主题中添加新文章

创建博客文章
Frontmatter
添加目录
标题
语法高亮
存储博客内容的图像
额外内容

这里有一些在 AstroPaper 博客主题中创建新文章的规则/建议、提示和技巧。

免费经典的木制桌子，上面有书写材料、复古时钟和皮包。库存照片 — 照片由 Pixabay 提供

创建博客文章

要撰写新博客文章，请在 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 格式编写。在 astro 文档中阅读有关 frontmatter 及其用法的更多信息。

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

属性	描述	备注
*title*	文章标题。(h1)	必填^*
*description*	文章描述。用于文章摘要和文章的网站描述。	必填^*
*pubDatetime*	ISO 8601 格式的发布日期时间。	必填^*
*modDatetime*	ISO 8601 格式的修改日期时间。（仅在修改博客文章时添加此属性）	可选
*author*	文章作者。	默认值 = SITE.author
*slug*	文章的 Slug。此字段是可选的。	默认值 = slugified file name
*featured*	是否在首页的精选部分显示此文章	默认值 = false
*draft*	标记此文章为“未发布”。	默认值 = false
*tags*	此文章的相关关键词。以数组 yaml 格式编写。	默认值 = others
*ogImage*	文章的 OG 图像。用于社交媒体分享和 SEO。这可以是远程 URL 或相对于当前文件夹的图像路径。	默认值 = `SITE.ogImage` 或生成的 OG 图像
*canonicalURL*	规范 URL（绝对路径），以防文章已存在于其他来源。	默认值 = `Astro.site` + `Astro.url.pathname`
*hideEditPost*	隐藏博客标题下的编辑文章按钮。这仅适用于当前博客文章。	默认值 = false
*timezone*	为当前博客文章指定 IANA 格式的时区。这将覆盖当前博客文章的 `SITE.timezone` 配置。	默认值 = `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: 文章标题
author: 您的名字
pubDatetime: 2022-09-21T05:17:19Z
slug: the-title-of-the-post
featured: true
draft: false
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
---src/data/blog/sample-post.md

添加目录

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

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

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

---
# 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/ 目录中。这些图像将通过 Image Service API 由 Astro 自动优化。

您可以使用相对路径或别名路径 (@/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 目录下的图像），建议压缩图像。这将影响网站的整体性能。

我推荐的图像压缩网站。

OG 图像

如果文章未指定 OG 图像，则将放置默认 OG 图像。虽然不是必需的，但在 frontmatter 中应指定与文章相关的 OG 图像。OG 图像的推荐尺寸为 1200 X 640 px。

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