核心特性#

• 可读性优先：纯文本格式，无冗余标签，直接阅读也自然流畅
• 语法简洁：基于标点符号设计，标记与语义高度一致（如 *强调* 直观易懂）
• 兼容性强：衍生版本丰富（Markdown Extra、MultiMarkdown 等），支持扩展表格、脚注等功能，可转换为 HTML、LaTeX、Docbook 等格式
• 灵感来源：源自纯文本电子邮件格式，兼顾写作效率与展示效果

主要用途#

• 撰写博客（支持 WordPress 等主流平台）
• 编写项目说明文档（如 README.md）
• 快速生成演讲 PPT、Word 文档、LaTeX 论文
• 数据科学领域：支持动态可重复性研究文档

1. 段落和换行#

• 段落：由连续行组成，空行（含仅空格/tab的行）分隔不同段落，无需缩进

• 强制换行：行尾加 2 个以上空格 + 回车，或用反斜线 \ + 回车

  1
  这是第一段，行尾加两个空格
  2
  强制换行显示
  3
  这是第二段（与上一段空行分隔）
  4
  这是第三段\
  5
  反斜线换行示例
  

2. 标题#

支持两种语法，推荐使用 Atx 形式（更灵活）：

1
# H1 一级标题
2
## H2 二级标题
3
### H3 三级标题
4
#### H4 四级标题
5
##### H5 五级标题
6
###### H6 六级标题

1
H1 一级标题
2
===
3
H2 二级标题
4
---

3. 块引言#

• 行首加 > ，支持嵌套（多层 >）和内部嵌套其他语法
• 可仅在段落第一行加 >，后续行自动继承

1
> 一级引言段落1
2
> 一级引言段落2
3
>
4
> > 嵌套二级引言
5
>
6
> 回到一级引言，支持嵌套列表：
7
> 1. 引言内有序列表
8
> 2. 列表项2
9
>
10
> > ## 引言内标题
11
> > `引言内代码`

4. 列表#

1
- 无序列表项1
2
- 无序列表项2
3
  - 嵌套子项（缩进 3 空格或 1 tab）
4
  - 嵌套子项
5
* 星号标记项（不推荐混合使用）
6
+ 加号标记项（不推荐混合使用）

1
1. 有序列表项1
2
2. 有序列表项2
3
  3. 嵌套子项（缩进）
4
  4. 嵌套子项
5
5. 有序列表项3

1
- 列表项1（含多段落）
2
  子段落内容（缩进 3 空格）
3
  子段落2
4

5
- 列表项2（空行分隔，自动加<p>标签）

5. 代码块#

1
普通段落：
2
    const a = 1; // 缩进 4 空格的代码块
3
    console.log(a);

1
```js
2
// 指定 JavaScript 语法高亮
3
function demo() {
4
  return "代码块";
5
}

1
```html
2
<div>嵌套代码块示例</div>
3
```

1
### 6. 分隔线
2
一行内用 3 个以上 `*`、`-`、`_`，行内无其他内容
3
```markdown
4
内容1
5
---
6
内容2
7
***
8
内容3
9
___

1. 链接#

1
[链接文本](https://example.com "可选标题，hover显示")
2
[相对路径链接](/about/ "内部页面")
3
[无标题链接](https://example.com)

1
// 正文引用
2
这是[示例链接][id1]，这是[重复引用链接][id1]
3

4
// 链接定义（可放文末）
5
[id1]: https://example.com "可选标题"
6
[google]: https://google.com/ "Google"
7

8
// 简化写法（链接文本=标识ID）
9
[Google][]
10
[google]: https://google.com/

2. 强调#

• 单 * 或 _：斜体（<em>）
• 双 * 或 _：粗体（<strong>）
• 符号需成对使用，不可混合

1
*斜体文本*（推荐）
2
_斜体文本_
3
**粗体文本**（推荐）
4
__粗体文本__
5
***粗斜体文本***

3. 行内代码#

用反引号 ` 包裹，含反引号时用多组反引号

1
行内代码：`console.log("hello")`
2
含反引号的代码：`` `code` 中的反引号 ``
3
HTML 标签示例：`<div class="demo">`

4. 图片#

语法与链接类似，前缀加 !，无宽高控制语法（需宽高时用 <img> 标签）

1
![替代文本（图片加载失败显示）](/path/to/img.webp "可选标题")
2
![网络图片](https://example.com/img.jpg)

1
![替代文本][imgId]
2
[imgId]: /path/to/img.webp "可选标题"

1
<img src="/path/to/img.webp" alt="替代文本" width="300" height="200">

5. 其他行内样式#

1. 表格#

• 表头与内容用 - 分隔，: 控制对齐（无 : 则默认左对齐）
• - 数量至少 1 个，可灵活调整

1
| 左对齐 | 居中对齐 | 右对齐 |
2
| :----- | :------: | -----: |
3
| 内容1  | 内容2    | 内容3  |
4
| 长文本内容 | 居中示例 | 数值100 |

2. 自动链接#

无需标记文本，直接用 <> 包裹网址或邮箱

1
<https://example.com>
2
<contact@example.com>

3. 转义字符#

用反斜线 \ 转义 Markdown 特殊符号，支持转义的符号：

1
\   反斜线
2
`   反引号
3
*   星号
4
_   底线
5
{}  大括号
6
[]  方括号
7
()  括号
8
#   井字号
9
+   加号
10
-   减号
11
.   英文句点
12
!   惊叹号

示例：\*这不是斜体\* → 这不是斜体

4. 行内 HTML#

支持直接插入 HTML 标签，块级标签需前后空行，且不缩进

1
普通段落
2

3
<div style="color: red;">HTML 块级标签，前后空行</div>
4

5
<span style="color: blue;">行内 HTML 标签</span>

注意：HTML 块内不解析 Markdown 语法

5. 快捷键#

使用示例#

语法格式#

1
::github{repo="用户名/仓库名"}

• repo 参数：必填，格式为「GitHub 用户名/仓库名称」（如 matsuzaka-yuki/Mizuki）

支持类型及示例#

基础语法#

1
:::类型标识
2
提示框内容（支持换行）
3
:::

:::类型标识

提示框内容（支持换行）

:::

自定义标题#

可修改提示框默认标题，语法如下：

1
:::note[我的自定义标题]
2
这是一个带有自定义标题的说明提示框。
3
:::

效果：

我的自定义标题

这是一个带有自定义标题的说明提示框。

GitHub 兼容语法#

同时支持 GitHub 官方提示框语法（无缝适配 GitHub 文档风格）：

1
> [!NOTE]
2
> GitHub 语法的说明提示框。
3
> 支持多行内容。
4

5
> [!TIP]
6
> GitHub 语法的技巧提示框。

效果：

NOTE

GitHub 语法的说明提示框。 支持多行内容。

TIP

GitHub 语法的技巧提示框。

注

GitHub 语法的说明提示框。 支持多行内容。

提示

GitHub 语法的技巧提示框。

使用示例#

1
这是普通文本，剧透内容：:spoiler[被隐藏的**剧透内容**（支持粗体等 Markdown 语法）]！

效果： 这是普通文本，剧透内容：被隐藏的剧透内容（支持粗体等 Markdown 语法）！

语法格式#

1
:spoiler[剧透内容（可包含 Markdown 语法）]

Mizuki 主题内置了 Mermaid 支持，让你可以在 Markdown 文档中轻松创建各种类型的图表和流程图。

基本语法#

Mermaid 使用 ```mermaid 代码块来定义图表：

支持的图表类型#

高级技巧#

最佳实践#

1. 保持简洁：避免在单个图表中展示过多信息，可以拆分为多个相关图表
2. 使用清晰的方向：TB（从上到下）和 LR（从左到右）是最常用的方向
3. 添加说明文字：为重要的节点和连接添加说明
4. 保持一致性：在整个文档中保持图表样式的一致性
5. 测试图表：在预览中检查图表是否按预期显示

常见问题#

参考资源#

• Mermaid 官方文档
• Mermaid 在线编辑器
• VuePress Mermaid 插件文档