博客写作语法指南

1. 双向链接（Wiki Links）

在数字花园中，文章之间可以像 Wiki 一样相互链接，建立知识网络。

基本语法

用 [[文章标题]] 包裹目标文章标题即可：

[[Obsidian 使用指南：打造你的第二大脑]]
[[本地优先：为什么我重新爱上了本地工具]]

渲染效果：

Obsidian 使用指南：打造你的第二大脑
本地优先：为什么我重新爱上了本地工具

带显示别名

如果想让链接文字与文章标题不同，用 | 分隔：

[[Obsidian 使用指南：打造你的第二大脑|Obsidian]]

渲染效果：

Obsidian

链接找不到会怎样？

如果 [[文章标题]] 中的标题在博客中找不到，链接会以特殊样式呈现（虚线下划线 + 淡化透明度），提示这是一个未解析的链接。

[[一篇不存在的文章]]

渲染效果：

[[一篇不存在的文章]]

2. Callout 容器

用 ::: 包裹内容块，并在 ::: 后指定类型，可创建醒目的信息提示框。

支持的类型

示例

Callout 的标记语法示例：

:::tip[小技巧]
这是提示框的内容
:::

嵌套列表

Callout 容器内可以正常使用 Markdown 语法，包括嵌套列表：

3. 脚注（Footnotes）

脚注用于在正文中添加补充说明或引用来源，而不打断阅读流。

基本语法

在需要添加脚注的位置使用 [^1] 标记，在文末用 [^1]: 定义内容：

鲁迅先生曾说过，时间就像海绵里的水，只要愿意挤，总还是有的 [^1]。

[^1]: 出自鲁迅《且介亭杂文》，原文为："时间就是性命。无端的空耗别人的时间，其实是无异于谋财害命的。"

渲染效果：

鲁迅先生曾说过，时间就像海绵里的水，只要愿意挤，总还是有的 ¹。

多次引用同一脚注

同一脚注可以在文中多次引用，使用相同的编号：

研究 [^2] 表明，写作时先列提纲可以显著提升文章逻辑性 [^2]。

[^2]: Kellogg, R. T. (2008). Training writing skills: A cognitive development perspective.

渲染效果：

研究 ² 表明，写作时先列提纲可以显著提升文章逻辑性 ²。

4. 文本高亮（Highlight）

用双等号 == 包裹文字，可以标记出重点内容，视觉上以黄色背景高亮：

这是普通文字，这是 ==需要强调的重点==，继续正文。

渲染效果：

这是普通文字，这是 需要强调的重点，继续正文。

使用场景

• 关键词汇
• 核心概念
• 重要结论
• 待复习内容

5. Emoji 快捷语法

输入 :emoji_name: 即可插入对应表情，比直接输入 Emoji 更具可读性：

6. 组合使用

各种语法可以自由组合，创造丰富的表达层次：

7. 完整对照表

8. 定义列表（Definition List）

术语和其定义可以用自然的方式写成列表，适合技术文档和概念解释。

语法

一行写术语，下一行以 : 开头写定义：

系统一
: 自动运行的快思考，不需要刻意努力
: 擅长模式识别和直觉判断

系统二
: 需要集中注意力的慢思考
: 负责复杂计算和逻辑推理

渲染效果

系统一

自动运行的快思考，不需要刻意努力

擅长模式识别和直觉判断

系统二

需要集中注意力的慢思考

负责复杂计算和逻辑推理

多术语

每个术语自动生成独立的 <dl> 块，术语之间保持分隔：

番茄工作法
: 一种时间管理方法，以 25 分钟为一个专注时段
: 由弗朗西斯科·西里洛于 1992 年发明

深度工作
: 在无干扰状态下专注进行的职业活动
: 使个人的认知能力达到极限

渲染效果：

番茄工作法

一种时间管理方法，以 25 分钟为一个专注时段

由弗朗西斯科·西里洛于 1992 年发明

深度工作

在无干扰状态下专注进行的职业活动

使个人的认知能力达到极限

9. 版本日志与文章关联

更新日志页（生长年轮）不只是版本记录——每个版本还可以关联一篇「详解文章」，把一次更新的来龙去脉讲清楚。这依赖 post 字段。

基本用法

编辑 src/data/changelog.json，在版本对象里加一个 post 字段，指向对应文章的路径：

{
  "version": "1.9.0",
  "date": "2026-08-15",
  "tag": "功能",
  "title": "划词高亮读书笔记 + 搜索升级 Pagefind",
  "post": "/blog/reading-notes-and-pagefind-search/",
  "changes": [ ]
}

• post 的值是文章路径，以 / 开头并以 / 结尾，指向 src/content/blog/ 下的某篇文章
• 添加后，更新日志页会在该版本卡片底部显示 「阅读这篇更新的详解 →」 链接
• 适合在大版本更新后写一篇介绍文章，然后在 changelog 里指过去；纯修 bug 的小版本可以不加

版本号规则

博客版本号遵循语义化约定，与更新日志页的「里程碑」标记一一对应：

• 发布（主题正式发布、重大上线）变更第一位：1.9.x → 2.0.0
• 里程碑（新功能、大改版）变更第二位：1.8.x → 1.9.0
• 其他更新（修 bug、小优化）只变更最后一位：1.9.0 → 1.9.1
• 次版本为 0（如 1.9.0、2.0.0）会在更新日志页自动标记为 「里程碑」

10. 阅读路径字段（TL;DR / 前置后续 / 继续阅读）

前面九节讲的都是正文里的写法。还有一组字段写在 frontmatter 里，控制的是文章开头和结尾长什么样——也就是读者要不要读下去、读完之后往哪走。

---
type: 'case-study'
tldr: |
  第一句给结论，不铺垫。
  第二句说清这篇解决什么问题。
  第三句写最终判断。
prerequisite: 'slug-of-previous'
followUp: 'slug-of-next'
readNext: ['slug-a', 'slug-b']
postscript: |
  发布之后又遇到了什么，补在这里。
---

几个要点：

• tldr 和 postscript 是多行文本，用 | 开头，内容必须缩进对齐
• prerequisite / followUp 表达的是文章之间的关系（前置 → 当前 → 后续），不是本文的章节；正文内部的导航只由右侧目录负责
• prerequisite / followUp / readNext 填的都是 slug（文件名去掉 .md），不是标题；写错不报错，会被静默忽略
• type 七类的选择和完整示例见 云图札记博文写作规范

常见问题