- 发布于
Markdown 完全指南与实用教程
- Authors

- Name
- clover
- @yu_xiaomo
Markdown 是一种轻量级的标记语言,旨在通过简单易读的纯文本格式,生成排版优雅的文档。它广泛应用于 GitHub 规范文档、个人博客、笔记软件(如 Obsidian、Notion)以及 AI 对话排版。
一、 基础排版语法
1.1 标题(Headings)
使用 # 符号表示标题,# 的数量代表标题的级别(共 1~6 级)。# 之后需要空一格。
# 一级标题(H1)
## 二级标题(H2)
### 三级标题(H3)
#### 四级标题(H4)
##### 五级标题(H5)
###### 六级标题(H6)
最佳实践:一篇文档中通常只使用一个
#(一级标题)作为总标题。
1.2 文本格式化(Formatting)
通过不同的符号为文本添加强调效果:
| 效果 | 语法示例 | 渲染呈现 |
|---|---|---|
| 加粗 | **加粗文本** 或 __加粗文本__ | 加粗文本 |
| 斜体 | *斜体文本* 或 _斜体文本_ | 斜体文本 |
| 斜体加粗 | ***斜体加粗*** | 斜体加粗 |
~~删除线文本~~ |
1.3 段落与换行(Paragraphs & Line Breaks)
- 分段:段落之间输入一个空行(按两次回车)。
- 段内换行:在上一行末尾加上两个及以上的空格再回车,或者直接回车。
1.4 分割线(Horizontal Rules)
在一行中使用三个或更多的 *、- 或 _,且该行不能有其他内容。
---
---
---
渲染效果:
二、 列表与引用
2.1 无序列表(Unordered Lists)
使用 -、* 或 + 加空格创建列表项:
- 项目一
- 项目二
- 子项目 A(缩进 2 或 4 个空格)
- 子项目 B
渲染效果:
- 项目一
- 项目二
- 子项目 A
- 子项目 B
2.2 有序列表(Ordered Lists)
使用数字加上英文句点 . 加空格:
1. 第一步
2. 第二步
3. 第三步
1. 子步骤 3.1
2. 子步骤 3.2
渲染效果:
- 第一步
- 第二步
- 第三步
- 子步骤 3.1
- 子步骤 3.2
2.3 任务列表 / 待办清单(Task Lists)
使用 - [ ] 表示未完成,- [x] 表示已完成:
- [x] 完成 Markdown 教程基础篇
- [ ] 掌握 Markdown 高级进阶
- [ ] 编写一份规范的 Readme 文档
渲染效果:
- 完成 Markdown 教程基础篇
- 掌握 Markdown 高级进阶
- 编写一份规范的 Readme 文档
2.4 引用区块(Blockquotes)
使用 > 开头表示引用。引用可以嵌套,也可以包含其他 Markdown 语法:
> 这是一段引用内容。
>
> > 这是嵌套的二级引用。
> > 引用内同样支持 **加粗** 和 [链接](https://example.com)。
渲染效果:
这是一段引用内容。
这是嵌套的二级引用。 引用内同样支持 加粗 和 链接。
三、 链接、图片与代码
3.1 链接(Links)
使用 [链接文本](URL "鼠标悬停提示词") 的格式:
基础链接:[百度搜索](https://www.baidu.com)
带提示词:[GitHub 官网](https://github.com '前往 GitHub')
3.2 图片(Images)
图片语法仅在链接语法前加上感叹号 !:

示例:

渲染效果: ![]()
3.3 代码(Code)
- 行内代码(Inline Code):使用一对反引号
`包裹。
请在终端中运行 `npm install` 命令。
渲染效果: 请在终端中运行 npm install 命令。
- 代码块(Code Blocks):使用三个反引号
```包裹,并在开头指定编程语言以实现语法高亮。
```python
def greet(name):
"""打印问候语的示例函数"""
print(f"Hello, {name}!")
greet("Markdown User")
```
渲染效果:
def greet(name):
"""打印问候语的示例函数"""
print(f"Hello, {name}!")
greet("Markdown User")
四、 表格(Tables)
使用竖线 | 分隔列,使用横线 - 分隔表头和表内容。可以在横线两侧加冒号 : 控制对齐方式。
| 功能 | 语法 | 兼容性 |
| :------- | :-----: | -----: |
| 左对齐 | `:---` | 优秀 |
| 居中对齐 | `:---:` | 良好 |
| 右对齐 | `---:` | 良好 |
渲染效果:
| 功能 | 语法 | 兼容性 |
|---|---|---|
| 左对齐 | :--- | 优秀 |
| 居中对齐 | :---: | 良好 |
| 右对齐 | ---: | 良好 |
五、 高级与扩展语法
5.1 转义字符(Escaping Characters)
如果需要显示 Markdown 的特殊符号而非触发格式,可在符号前添加反斜杠 \:
\*这段文字不会变成斜体\*
\# 这不是标题
渲染效果:
*这段文字不会变成斜体*
# 这不是标题
5.2 脚注(Footnotes)
使用 [^标识] 声明脚注标号,并在文档末尾或任意位置定义其内容:
这是一个包含脚注的句子[^1]。
[^1]: 这是脚注的具体解释内容。
渲染效果:
这是一个包含脚注的句子1。
5.3 数学公式(LaTeX / MathJax - MDX 兼容写法)
在 MDX 中,公式中的 {} 需要进行转义 \{ 和 \},防止 MDX 的 Acorn 解析器将其当做 JS 表达式解析:
- 行内公式:使用
$公式$包裹。 - 块级公式:使用
$$公式$$包裹。
行内公式:爱因斯坦的质能方程是 $E = mc^2$。
块级公式:
$$
\int_{\{0\}}^{\{\infty\}} e^{\{-x^2\}} dx = \frac{\sqrt{\pi}}{2}
$$
渲染效果:
行内公式:爱因斯坦的质能方程是 。
块级公式:
5.4 JSX / HTML 语法支持
在 MDX 中,必须遵守 JSX 语法规范(内联样式需传入双大括号 style={{...}},标签需要关闭):
<p style={{ textAlign: 'center' }}>居中文本内容</p>
<font color="red">这段文字呈现红色</font>
<span style={{ backgroundColor: 'yellow' }}>带有黄底高亮的效果</span>
渲染效果:
居中文本内容
这段文字呈现红色 带有黄底高亮的效果六、 编写规范与习惯建议
- 统一空格:在 Markdown 符号与文字之间保留一个半角空格(例如
# 标题,- 列表),增强可读性。 - 规范文件后缀:MDX 文件标准后缀名为
.mdx。 - 分段留空:段落与段落、段落与代码块或表格之间保留一个完整的空行。
- 组件交互:在 MDX 中,你还可以直接使用
import导入并使用 React/Vue 组件。
Footnotes
这是脚注的具体解释内容。 ↩