博客写作功能指南

1 Jan 2026

3 min read

guide markdown

本文档介绍了本博客系统集成的核心写作功能，旨在提升文章的表现力与专业度。

1. 基础增强 (GFM)

基于 remark-gfm，我们支持了更丰富的 Markdown 标准语法。

1.1 脚注 (Footnotes)

对某个词或句子的补充说明，会自动链接到文章底部。

语法：

1
这是一个需要解释的词[^1]。
2

3
[^1]: 这是该词的解释内容。

效果：

这是一个需要解释的词¹。

1.2 表格 (Tables)

快速创建结构化数据展示。

语法：

1
| 功能 | 状态 | 备注 |
2
| :--- | :---: | ---: |
3
| GFM | ✅ | 基础支持 |
4
| Citations | ✅ | 学术必备 |

效果：

功能	状态	备注
GFM	✅	基础支持
Citations	✅	学术必备
Callouts	✅	样式增强

1.3 任务列表 (Task List)

适合用于 TODO 列表或进度追踪。

语法：

1
- [x] 已完成的任务
2
- [ ] 待办任务

效果：

已完成的任务
待办任务

2. 学术引用 (Citations)

基于 rehype-citation，支持专业的学术文献引用。

2.1 配置

在文章 Frontmatter 中指定 .bib 文件路径：

1
---
2
bibliography: public/bibliography.bib
3
---

2.2 引用语法

使用 BibTeX 中的引用 Key 进行引用。

语法：

1
根据 Vaswani 等人的研究 [@vaswani2017attention]...

效果：

根据 Vaswani 等人的研究 [1]…

系统会自动在文章末尾生成参考文献列表。

3. 自定义标注块 (Callouts)

基于 remark-directive，我们实现了类似 Obsidian/GitHub 的 Callout 块，用于突出显示特定内容。

语法：

1
:::note
2
这是一个普通的**笔记**块。
3
:::
4

5
:::tip
6
这是一个**提示**块，用于给出建议。
7
:::
8

9
:::warning
10
这是一个**警告**块，请注意。
11
:::
12

13
:::important
14
这是一个**重要**信息块。
15
:::
16

17
:::caution
18
这是一个**危险**警告块。
19
:::
20

21
:::cite
22
这是一个**引用**块。
23
:::

效果：

这是一个普通的笔记块。

这是一个提示块，用于给出建议。

这是一个警告块，请注意。

这是一个重要信息块。

这是一个危险警告块。

这是一个引用块（中文正体）。

Stay hungry, stay foolish. (English Italic)

知行合一。

Knowledge and action are one.

4. 流程与架构图 (Mermaid)

使用 Mermaid 语法绘制流程图、时序图、甘特图等。（需配合 div 容器或代码块使用，具体视配置而定，以下为通用示例）。

语法：

1
<div class="mermaid">
2
graph TD;
3
    A[开始] --> B{判断};
4
    B -- 是 --> C[执行操作];
5
    B -- 否 --> D[结束];
6
    C --> D;
7
</div>

效果：

graph TD; A[开始] --> B{判断}; B -- 是 --> C[执行操作]; B -- 否 --> D[结束]; C --> D;

5. 文本特效 (Text Effects)

使用 :directive[text] 语法为文本添加颜色、高亮或特殊效果。

5.1 基础颜色

支持 :color[text] 格式。

1
- :red[红色文字] (`:red[...]`)
2
- :blue[蓝色文字] (`:blue[...]`)
3
- :green[绿色文字] (`:green[...]`)
4
- :yellow[黄色文字] (`:yellow[...]`)
5
- :purple[紫色文字] (`:purple[...]`)
6
- :orange[橙色文字] (`:orange[...]`)
7
- :pink[粉色文字] (`:pink[...]`)
8
- :gray[灰色文字] (`:gray[...]`)

效果：

红色文字
蓝色文字
绿色文字
黄色文字
紫色文字
橙色文字
粉色文字
灰色文字

5.2 特殊效果

1
- **彩虹特效**：`:rainbow[这是一段彩虹文字]`
2
- **发光效果**：`:glow[发光文字]`
3
- **模糊效果**：`:blur[模糊文字]`
4
- **防剧透**：`:spoiler[剧透警告！鼠标悬停查看]` (默认模糊，悬停显示)
5
- **高亮**：`:highlight[高亮背景]`

效果：

彩虹特效：这是一段彩虹文字
发光效果：发光文字
模糊效果：模糊文字
防剧透：剧透警告！鼠标悬停查看 (默认模糊，悬停显示)
高亮：高亮背景

5.3 字体样式

手写体：:font-hand[Using handwritten font style]

效果：

手写体：Using handwritten font style

6. 总结

插件	用途	场景
`remark-gfm`	脚注、表格、任务列表	通用写作增强
`rehype-citation`	参考文献	研究型、技术深究型文章
`remark-directive`	Callouts	提示、警告、旁注
`mermaid`	流程图	架构设计、逻辑梳理

7. 参考文献

[1]

A. Vaswani et al., “Attention is all you need,” in Advances in neural information processing systems, 2017.

这是脚注的实际渲染效果。 ↩