如何在本项目里写一篇博客文章

这篇文章分成两部分：先讲文章的 frontmatter 配置项，再讲正文里可以使用的 Markdown、GFM、MDX 写法。所有示例都可以直接复制到自己的文章里。

文件放在哪里

文章统一放在 src/content/blog/ 目录下，支持 .md 和 .mdx 两种扩展名。

文件路径会直接决定访问地址：

• src/content/blog/hello.md → /blog/hello/
• src/content/blog/notes/astro/tips.md → /blog/notes/astro/tips/

可以按分类建子目录，也可以把文章全部平铺在 blog/ 下。子目录只影响 URL，不影响分类和标签；分类、标签仍然由 frontmatter 决定。

一、Frontmatter 配置项

frontmatter 是文章顶部两行 --- 之间的内容，用来描述文章元信息。

---
title: 文章标题
description: 文章摘要
pubDate: 2026-10-21
---

字段总览

title 和 description

两个都是必填字段。description 会出现在文章列表、<meta name="description"> 和社交分享信息里，建议写一两句完整的话，不要只堆关键词。

title: 用 Astro 搭建个人博客
description: 从零开始搭建一个支持 Markdown、RSS 和暗色模式的静态博客

pubDate 和 updatedDate

pubDate 必填，支持 YYYY-MM-DD 或完整时间：

pubDate: 2026-10-21
# 或者
pubDate: 2026-10-21T10:30:00+08:00

文章详情页的“写作日期”会优先读取该文件在 Git 中的首次提交时间：

• 已经提交过的文章：显示 Git 首次提交日期
• 尚未提交的新文章：回退到 frontmatter 里的 pubDate
• 构建环境没有完整 Git 历史时：同样回退到 pubDate

所以本地新写完文章、还没提交时，详情页显示的仍然是 frontmatter 里的日期，提交后才会以 Git 时间为准。部署到 CI 时如果希望使用 Git 时间，需要保证构建环境有完整历史，例如 GitHub Actions 的 actions/checkout 设置 fetch-depth: 0。

注意：文章列表的排序和列表上的日期仍然使用 frontmatter 的 pubDate，详情页使用的是 Git 首次提交时间。建议让两者尽量保持一致。

updatedDate 当前只是可选保留字段，文章页暂时不展示更新日期。

updatedDate: 2026-10-22

author

支持单个作者或多个作者：

# 单个作者
author: 廿四

# 多个作者
author:
  - 廿四
  - 张三

不填时，顶部会回退到站点默认作者（src/config/site.ts 里的 siteMeta.author.name）。普通文章的底部作者卡片展示站点作者，用于表示这是本站发布的内容；转载文章请使用下面的 source 字段。

source（转载来源）

如果文章是转载的，填写 source 后，顶部不再显示作者，而是显示“转载自 xxx”：

source:
  name: 张洪Heo
  url: https://blog.zhheo.com/p/xxxx.html

• name 必填，显示来源名称
• url 可选，填写后会生成可点击的原文链接

转载文章的底部作者卡片也会切换为来源信息，并提示版权归原作者所有。此时可以不填 author。

categories 和 tags

分类和标签都支持字符串或数组：

# 单个分类
categories: 前端

# 多个分类
categories:
  - 前端
  - Astro

# 单个标签
tags: Markdown

# 多个标签
tags:
  - Astro
  - Markdown
  - 教程

• 分类显示在文章标题上方，点击会进入对应分类页
• 标签显示在文章正文末尾，点击会进入对应标签页

一个完整的 frontmatter 示例

---
title: 使用 Astro 内容集合管理文章
description: 介绍 content collections 的目录结构、frontmatter 和类型校验
pubDate: 2026-10-21
updatedDate: 2026-10-22
author:
  - 廿四
categories:
  - 前端
  - Astro
tags:
  - Astro
  - 教程
---

二、正文支持的写法

项目的 Markdown 处理器是 Astro 7 默认的 Sätteri，GFM（GitHub Flavored Markdown）默认开启。下面这些写法都可以直接在正文里使用。

标题与目录

正文支持 h1 到 h6，但右侧目录只收集 h2 和 h3。写文章时建议从 h2 开始，h3 作为小节。

## 二级标题

### 三级标题

#### 四级标题

标题会自动生成 id，所以可以直接用锚点跳转：

[跳到第二节](#二正文支持的写法)

段落与文字样式

普通段落。

**加粗**、_斜体_、~~删除线~~、`行内代码`。

[站内链接](/pages/about) 和 [外部链接](https://astro.build)。

渲染效果：

普通段落。

加粗、斜体、删除线、行内代码。

站内链接 和 外部链接。

列表

无序列表、有序列表和嵌套列表都支持：

- 第一项
- 第二项
  - 嵌套项
- 第三项

1. 第一步
2. 第二步
3. 第三步

渲染效果：

• 第一项
• 第二项
  • 嵌套项
• 第三项

1. 第一步
2. 第二步
3. 第三步

任务列表

GFM 任务列表会渲染成复选框：

- [x] 已完成
- [ ] 未完成

渲染效果：

• 已完成
• 未完成

引用

> 这是一段引用文字。
>
> —— 出处

渲染效果：

这是一段引用文字。

—— 出处

表格

GFM 表格会自动套上可横向滚动的容器，表头会使用浅色背景：

| 字段        | 类型   | 必填 |
| ----------- | ------ | ---- |
| title       | string | 是   |
| description | string | 是   |
| pubDate     | Date   | 是   |
| categories  | string | 否   |

渲染效果：

代码块

在代码围栏后写上语言，会启用语法高亮、语言栏、行号和复制按钮：

```ts
interface Post {
	title: string;
	pubDate: Date;
}
```

渲染效果：

interface Post {
	title: string;
	pubDate: Date;
}

const post: Post = {
	title: 'Hello',
	pubDate: new Date(),
};

常用语言标识：

ts / js / vue / astro / bash / json / yaml / md / css / html

代码块右上角有“复制”按钮，点击后会复制完整代码；行号不会进入复制内容。

高亮指定行

在语言后面紧跟 {行号} 可以高亮代码行，支持单个行号和区间：

```ts{2,5-6}

```

渲染效果：

interface Post {
	title: string;
	pubDate: Date;
}

const post: Post = {
	title: 'Hello',
	pubDate: new Date(),
};

行号从 1 开始，多个行号用逗号分隔。

数学公式

行内公式使用单个 $，独立公式使用两个 $：

行内公式：$E = mc^2$

$$
a^2 + b^2 = c^2
$$

渲染效果：

行内公式：$E = mc^2$

公式由 KaTeX 在构建时渲染，不需要额外引入脚本。

提示块

基本语法：

:::tip
提示内容
:::

支持 7 种名称，未写标题时会使用默认标题：

默认标题

:::tip
提示内容
:::

:::info
信息内容
:::

:::note
笔记内容
:::

:::warning
警告内容
:::

:::caution
注意内容
:::

:::important
重要内容
:::

:::danger
危险内容
:::

渲染效果：

自定义标题

在名称后的方括号里写标题，所有类型都适用：

:::tip[自定义标题]
这段内容会使用自定义标题。
:::

渲染效果：

容器内的 Markdown

提示块内部可以正常写段落、列表、链接和行内代码：

:::note
支持 **加粗**、`行内代码` 和 [链接](/)。

- 列表项一
- 列表项二
  :::

渲染效果：

注意：Sätteri 的容器语法要求 ::: 后紧跟名称，::: tip（中间有空格）不会生效，要写成 :::tip。

卡片

:::card
卡片内容
:::

渲染效果：

图片

普通 Markdown 图片会居中显示，点击可以打开大图预览：

![站点 Logo](/niansi-logo.svg)

渲染效果：

注意事项：

• 图片默认最大宽度为容器宽度，最大高度为 450px
• 点击图片会打开预览，按 Esc 或点击遮罩关闭
• 如果图片被链接包裹（例如徽章），点击会优先跳转链接，不会触发预览

[![站点 Logo](/niansi-logo.svg)](/)

分割线

---

渲染效果：

自动链接

GFM 会自动把裸链接转成可点击链接：

https://astro.build

渲染效果：https://astro.build

脚注

GFM 脚注默认可用：

这是一个脚注[^1]。

[^1]: 这是脚注内容。

渲染效果：

这是一个脚注¹。

原始 HTML

正文里可以直接写 HTML，项目已经为 details / summary 准备了样式：

<details>
	<summary>点我展开</summary>

	这里是折叠内容。
</details>

渲染效果：

MDX

把文件扩展名从 .md 改成 .mdx，就可以在正文里使用 JSX 表达式和 import 组件：

---
title: 使用 MDX 写文章
description: 在文章里直接使用组件
pubDate: 2026-10-21
---

import HelloCard from '../../components/HelloCard.astro';

## 组件示例

<div style="max-width: 320px">
	<HelloCard />
</div>

几点说明：

• MDX 文件同样放在 src/content/blog/ 下，frontmatter 写法不变
• import 路径相对于当前 .mdx 文件
• 可以导入 .astro、.vue 组件
• 如果需要客户端交互，组件仍然需要按 Astro 的规则添加 client:* 指令

最后，正文写完后，详情页会自动生成目录、代码复制、图片预览、上下篇导航和作者卡片，这些都不需要手动处理。