Markdown 语法规范
创建于：2025-08-11 最后更新：2025-09-13
简介说明
本页列出的 Markdown 语法已涵盖本手册所有页面的构建需求。原则上，未提及的语法特性与元素构建方式，均不在手册编写范围内，以此确保文档结构的简洁性。
警告
遇到任何非预期的渲染结果时，建议直接从本页面复制相应代码使用，生产环境中请不要尝试任何未定义的行为。
快速开始
以下模板快速地实现了一个文档的基本结构：
| template.md |
|---|
| # Page title
> Created：2025-01-01 | Last update：2025-01-01
## Section 1
Content...
## Section 2
Content...
|
通用 Markdown 语法
下方代码块所展示元素的创建方式均符合 CommonMark 核心规范。各元素嵌套使用时，缩进决定层级，空行决定边界。
| *Italic*
**Bold**
***Italic and Bold***
|
| > Blockquote
>
> > Nested Blockquotes
|
[Link][1]
...
[1]: https://example.com "title"
![Image][1]
...
[1]: https://example.com "title"
| - List
- List
- Escape using `\-`
|
| 1. One
1. Two
1. Escape using `1\.`
|
| <!-- Horizontal rule: -->
---
|
| `Inline code`
<!-- Example with backticks: -->
`` `foo` `bar` ``
|
| ```
print '3 backticks or indent 4 spaces'
```
|
<span id="anchor" aria-hidden="true"></span>
...
[Link](#anchor)
扩展 Markdown 语法
1. 通用语法扩展
参考附录内 Python Markdown 相关链接，可以对通用 Markdown 语法的功能进行扩展。
-
标题语法扩展：
- 本手册采用 Setext 风格的方式来创建标题，从而增加源码的可读性。
- 建议通过
{ } 包裹的 id 和 data-toc-label 标签来分别修改锚点和目录。
-
代码块语法扩展：
- 可以指定语言进行高亮，支持语言参考该页面。
- 代码块额外提供的选项还有：
title、linenums、hl_lines。
2. 新增元素扩展
下方代码块所展示元素的创建方式均不属于 CommonMark 核心规范。各元素嵌套使用时，缩进决定层级，空行决定边界。
- Metadata 元素可以参考该页面
- Admonition 元素可以参考该页面
- Key 元素可以参考该页面。
FootnotesContent[^1]
...
[^1]: Footnote.
Abbreviation[Hover me]
...
*[Hover me]: Abbreviation
| Task Lists |
|---|
| - [x] Finished
- [ ] Unfinished
- [ ] ...
|
| Definition Lists |
|---|
| Term to be defined
: Definition text
|
| Metadata |
|---|
| ---
title: Page title
---
|
| Admonition |
|---|
| !!! example "Example"
Keep It Simple, Stupid.
|
Keys++ctrl+alt+del++
++ctrl+alt+"My Special Key"++
++cmd+alt+"Ü"++
Caret<!-- This is better than Italic -->
^^Insert me^^
3. 其他复杂元素
该部分内容不作详细介绍，仅使用下方代码块内所展示的用法，不依赖除此以外的任何高级特性。细节注意高亮代码示意即可。
Single Line Embedding``` py
--8<-- "filename.py:1:3,5:6"
--8<-- "filename.py:2:"
--8<-- "; skip.py"
;--8<-- "skip.py"
```
Block Format Embedding``` py
--8<--
filename.py
; skip.py
--8<--
```
| Card Grid |
|---|
| <div class="grid cards" markdown>
- Card grid 1.
- Card grid 2.
- Card grid 3.
---
:octicons-file-code-16: Title
- Card grid 4.
---
:octicons-arrow-right-16: More
</div>
|
| Generic Crid |
|---|
| <div class="grid" markdown>
Card grid content.
{ .card }
> Blockquote
=== "Content tab"
1. One
1. Two
``` title="Code block"
Any code ...
```
</div>
|
4. 数学公式元素
用如下 HTML 元素包裹代码块，可以展示其渲染结果。效果如 KaTeX 代码块下半部分所示。
<div class="result" markdown> Any markdown code ... </div>
| KaTeX |
|---|
| Fourier Transform:
\\[
\mathcal{F} \{f(t)\} (\omega) = \int_{-\infty}^{\infty} f(t) e^{-i\omega t} dt.
\\]
|
Fourier Transform:
\[
\mathcal{F} {f(t)} (\omega) = \int_{-\infty}^{\infty} f(t) e^{-i\omega t} dt.
\]
手册规范
总结上述所有内容，在本手册中，最终确定的文档基本结构模板如下方代码块所示。在任何情况下，你都可以复制这 13 行代码作为文档的开头，略作修改后开始内容的产出。
| new-template.md |
|---|
| ---
title: Page title
---
Page title { id="New-title" }
=============================
> 创建于：2025-01-01 | 最后更新：2025-01-01
---
Section 1 { id="New-section" }
------------------------------
...
|
其他细则
-
本规范对文档结构与层次的约定如下：
- 通过
--- 生成水平分割线，划分各二级标题的所属内容。
- 尽量减少三级标题的使用，且不使用四级标题。
- 尽量减少或避免使用嵌套内容，嵌套层级过多易导致不必要的复杂化。
-
本规范未提及的其他元素与细节说明如下：
- 插入图片时，如需保证排版效果，可通过嵌入 HTML 标签灵活调整图片样式。
- 本规范未提供表格相关元素的规定，如需使用表格，可引入 HTML 表格实现。
附录：相关链接