在 AstroPaper 主题中添加新文章

以下是在 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

💡 提示：你也可以在前言中覆盖博客文章的 slug（别名）。详情请参阅下一节。

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

FrontMatter

前言是存储关于博客文章（文章）一些重要信息的主要地方。前言位于文章顶部，以 YAML 格式编写。在 astro documentation中阅读更多关于前言及其用法的内容。

以下是每篇文章的前置页属性列表。

提示！你可以通过在控制台运行 new Date().toISOString() 获取 ISO 8601 格式的日期时间。不过记得去掉引号。

前置页中只有 title, description 和 pubDatetime 字段是必须指定的。

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

slug 是 URL 的唯一标识符。因此， slug 必须是唯一的，且与其他文章不同。 slug 中的空格应该用 - 或 _ 分隔，但推荐使用 - i。Slug 是使用博客文章文件名自动生成的。但是，你可以在博客文章的前言中定义你的slug 。

例如，如果博客文件名是 adding-new-post.md，而你没有在前言中指定 slug，Astro 将使用文件名自动为博客文章创建一个 slug。因此，slug 将是 adding-new-post。但如果你在前言中指定了 slug ，这将覆盖默认的 slug。你可以在 Astro Docs中阅读更多相关内容。

如果你在博客文章中省略了 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:
  - some
  - example
  - tags
ogImage: ../../assets/images/example.png
description: 这是示例文章的示例描述。
# canonicalURL: https://example.org/my-article-was-already-posted-here
---src/data/blog/sample-post.md

添加目录

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

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

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

---
# FrontMatter
---

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

## 目录

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

标题

关于标题有一点需要注意。AstroPaper 博客文章使用标题（FrontMatter中的 title）作为文章的主标题。因此，文章中的其余标题应使用 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 如果你不想使用它，可以像这样简单地移除它：

pnpm remove @shikijs/transformers

// ...
import {
  transformerNotationDiff,
  transformerNotationHighlight,
  transformerNotationWordHighlight,
} from "@shikijs/transformers";

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkToc, [remarkCollapse, { test: "Table of contents" }]],
    shikiConfig: {
      // For more themes, visit 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 中设置优化图片的样式，你应该 use MDX.

存放在 src/assets/ 目录下（推荐）

你可以将图片存放在 src/assets/ 目录下。这些图片将通过 Image Service API被 Astro 自动优化。

你可以使用相对路径或别名路径 (@/assets/) 来引用这些图片。.

示例：假设你想展示路径为 example.jpg 的 /src/assets/images/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 语法 或 HTML img 标签 显示。

示例：假设 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 图片。OG 图片的推荐尺寸为 1200 X 640 px。

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