博客写作指南

这篇文章是给自己留着查的。以后写新文章时，不需要回头翻模板作者的英文示例，只要照着这里的格式写就够了。

Table of contents

一篇文章放在哪里

所有博客文章都放在 src/data/blog/ 目录下，文件格式是 Markdown，扩展名是 .md。

最简单的结构是：

src/data/blog/
  我的第一篇博客.md
  博客写作指南.md

也可以用文件夹整理文章：

src/data/blog/
  2026/
    一篇文章.md

默认情况下，文件夹会影响文章网址。比如 src/data/blog/2026/一篇文章.md 的路径会类似 /posts/2026/yi-pian-wen-zhang。

如果只是想用文件夹整理，不想让它出现在网址里，可以让文件夹名以下划线开头：

src/data/blog/
  _草稿资料/
    一篇文章.md

文章头部信息

每篇文章最上方的 --- 到 --- 之间叫 frontmatter，用来告诉博客这篇文章的标题、时间、标签和发布状态。

推荐模板：

---
author: Shan
pubDatetime: 2026-04-22T00:00:00+08:00
title: 文章标题
slug: article-slug
featured: false
draft: false
tags:
  - 随笔
description: 一句话介绍这篇文章。
---
正文从这里开始。src/data/blog/文章标题.md

常用字段：

草稿和发布

写文章时可以先设为草稿：

draft: true

正式发布时改成：

draft: false

草稿不会出现在正式构建出来的网站里。开发预览时，部分列表也会过滤草稿，所以最好把真正要发布的文章明确写成 draft: false。

如果发布时间是未来时间，正式网站会等到发布时间接近后才显示。平时为了减少混乱，建议手动写当天或过去的时间。

精选文章和普通文章

首页会把 featured: true 的文章放在 Featured 区域，把其他已发布文章放在 Recent Posts 区域。

featured: true

适合放在精选区的文章：

• 代表你博客方向的文章
• 你希望新读者先读的文章
• 长期有效的整理型文章

普通随笔、临时记录、测试性内容可以用：

featured: false

标题层级

文章的一级标题已经由 frontmatter 里的 title 提供，所以正文里建议从二级标题开始。

## 二级标题

正文。

### 三级标题

更细的内容。

不要在正文里再写一个 # 一级标题，否则页面结构会显得重复。

自动目录

如果希望文章里出现自动目录，单独写一行：

## Table of contents

注意这里必须写英文 Table of contents，因为当前模板就是按这句话识别并生成目录的。中文文章也可以这样写。

目录通常放在开头简介后面：

这篇文章先简单说明我要写什么。

## Table of contents

## 第一部分

段落、强调和链接

普通段落直接写文字，段落之间空一行。

这是第一段。

这是第二段。

常用行内格式：

这是 **加粗**，这是 _斜体_，这是 `行内代码`。

这是一个 [链接](https://example.com)。

显示效果：

这是 加粗，这是 斜体，这是 行内代码。

这是一个 链接。

引用

引用适合放摘录、提醒、临时想法。

> 这是一段引用。
> 第二行仍然属于同一个引用块。

显示效果：

这是一段引用。 第二行仍然属于同一个引用块。

列表

无序列表：

- 第一项
- 第二项
- 第三项

有序列表：

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

如果列表项里有多段内容，第二段前面要空一行，并缩进两个空格：

- 第一项。

  这是第一项里的补充段落。

- 第二项。

表格

表格适合放对比、清单、字段说明。

| 项目       | 说明     |
| ---------- | -------- |
| `draft`    | 是否草稿 |
| `featured` | 是否精选 |

显示效果：

代码块

普通代码块：

```js
const message = "Hello";
console.log(message);
```

带文件名的代码块：

```ts file="src/config.ts"
export const SITE = {
  title: "杉杉的话",
};
```

显示效果：

export const SITE = {
  title: "杉杉的话",
};src/config.ts

高亮代码行

这个模板支持 Shiki 的代码标记，可以在代码注释里写特殊标记。

高亮一行：

```ts
const title = "杉杉的话"; 
const lang = "zh-CN";
```

显示新增和删除：

```diff
- lang: "en"
+ lang: "zh-CN"
```

在 TypeScript、JavaScript、CSS 等代码块里，也可以用：

```ts
const oldValue = "en"; 
const newValue = "zh-CN"; 
```

这些标记适合写技术文章、配置变更、重构说明。

图片

如果图片在 public 目录下，可以这样引用：

![图片说明](/example.png)

如果图片放在 src/assets 下面，可以用相对路径或别名路径：

![图片说明](@/assets/images/example.png)

写图片时尽量补上有意义的图片说明，也就是 [] 里的文字。它对可访问性和搜索引擎都有帮助。

如果想要图片说明文字，可以直接写 HTML：

<figure>
  <img src="/example.png" alt="图片说明" />
  <figcaption>这里是图片说明。</figcaption>
</figure>

参考文献

参考文献使用和微信公众号排版助手一致的块语法。块里面可以继续写普通 Markdown，比如有序列表、链接、行内代码和加粗。

:::reference

1. 刘慈欣. 三体[M]. 重庆: 重庆出版社, 2008.
2. Smith J. [Writing for Digital Reading](https://example.com)[J]. Journal of Content Design, 2024.
   :::

显示效果：

也可以把开头写成 :::references 或 :::ref。

推荐卡片

推荐卡片也沿用排版助手的写法。cover 和 title 必填，meta、desc 可选；type 支持 portrait 和 square。

:::recommend
type: square
cover: ![AstroPaper 示例图](/astropaper-og.jpg)
title: AstroPaper
meta: 博客模板 / Astro / Markdown
desc: 一个适合写技术记录、生活札记和长期整理的轻量博客模板。
:::

显示效果：

AstroPaper

博客模板 / Astro / Markdown

一个适合写技术记录、生活札记和长期整理的轻量博客模板。

推荐卡片开头也可以写成 :::recommendation 或 :::card。封面字段也可以写成 image，简介字段也可以写成 summary。

文章封面和分享图

单篇文章可以通过 ogImage 指定分享图：

ogImage: ../../assets/images/example.png

也可以用远程图片：

ogImage: "https://example.com/example.png"

如果不写 ogImage，当前站点开启了动态 OG 图生成，会自动用文章信息生成一张分享图。

标签

标签写在 tags 下面：

tags:
  - 随笔
  - 技术
  - 读书

建议不要一开始建太多标签。标签的意义是帮助以后回看，而不是把每篇文章都分得很细。

可以先用几个稳定标签：

• 随笔
• 技术
• 读书
• 生活
• 记录

摘要

description 会出现在文章列表、RSS 和网页元信息里。

好的摘要不用长，说明这篇文章在干什么就行：

description: 记录一次把博客模板整理成个人写作空间的过程。

不建议写得太空：

description: 随便写写。

修改时间

如果文章只是改错别字，不一定要写修改时间。如果文章内容大幅更新，可以加：

modDatetime: 2026-04-23T12:30:00+08:00

文章排序会参考 modDatetime，所以加了修改时间后，旧文章也可能重新排到前面。

原文地址

如果文章最早发在别的平台，再同步到这里，可以写：

canonicalURL: https://example.com/original-post

如果文章首发在自己的博客，就不用写。

可以直接写 HTML

Markdown 里可以直接插入 HTML。比如：

<kbd>Command</kbd> + <kbd>K</kbd>

适合少量特殊排版。不要把整篇文章都写成 HTML，否则以后维护会变麻烦。

当前没有默认启用的东西

这个模板有些能力可以扩展，但当前项目没有默认启用，所以先不要当成现成功能来用：

• 数学公式：需要额外安装和配置 KaTeX 或类似插件。
• 评论区：需要接入 Giscus 或其他评论系统。
• 复杂图表：建议以后按需求单独处理。

先把文章写顺，比一开始堆很多功能更重要。

我的写作流程

以后写文章可以按这个顺序：

1. 复制 src/data/blog/博客模板.md。
2. 改文件名，比如 一次博客整理.md。
3. 改 title、slug、description 和 tags。
4. 写正文，正文标题从 ## 开始。
5. 没写完就保持 draft: true。
6. 准备发布时改成 draft: false。

一份最小可用模板

以后忘记格式，就复制这一段：

---
author: Shan
pubDatetime: 2026-04-22T00:00:00+08:00
title: 文章标题
slug: article-slug
featured: false
draft: true
tags:
  - 随笔
description: 一句话介绍这篇文章。
---

正文：

开头先写一小段，说明这篇文章为什么要写。

## Table of contents

## 第一部分

这里写正文。

## 第二部分

这里继续写。

写博客不需要一次把格式想完。先把想法写下来，再慢慢整理成能被别人读懂的样子。