发布于

Markdown 完全指南与实用教程

Authors

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

渲染效果:

  1. 第一步
  2. 第二步
  3. 第三步
    1. 子步骤 3.1
    2. 子步骤 3.2

2.3 任务列表 / 待办清单(Task Lists)

使用 - [ ] 表示未完成,- [x] 表示已完成:

- [x] 完成 Markdown 教程基础篇
- [ ] 掌握 Markdown 高级进阶
- [ ] 编写一份规范的 Readme 文档

渲染效果:

  • 完成 Markdown 教程基础篇
  • 掌握 Markdown 高级进阶
  • 编写一份规范的 Readme 文档

2.4 引用区块(Blockquotes)

使用 > 开头表示引用。引用可以嵌套,也可以包含其他 Markdown 语法:

> 这是一段引用内容。
>
> > 这是嵌套的二级引用。
> > 引用内同样支持 **加粗** 和 [链接](https://example.com)。

渲染效果:

这是一段引用内容。

这是嵌套的二级引用。 引用内同样支持 加粗 和 链接。

三、 链接、图片与代码

使用 [链接文本](URL "鼠标悬停提示词") 的格式:

基础链接:[百度搜索](https://www.baidu.com)
带提示词:[GitHub 官网](https://github.com '前往 GitHub')

渲染效果: 基础链接:百度搜索
带提示词:GitHub 官网

3.2 图片(Images)

图片语法仅在链接语法前加上感叹号 !:

![图片替代文本/Alt](图片的URL或相对路径 '可选标题')

示例:

![Markdown Logo](https://markdown-here.com/img/icon256.png 'Markdown 标志')

渲染效果: Markdown Logo

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}
$$

渲染效果:
行内公式:爱因斯坦的质能方程是 E=mc2E = mc^2。

块级公式:

∫{0}{∞}e{−x2}dx=π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>

渲染效果:

居中文本内容

这段文字呈现红色 带有黄底高亮的效果

六、 编写规范与习惯建议

  1. 统一空格:在 Markdown 符号与文字之间保留一个半角空格(例如 # 标题,- 列表),增强可读性。
  2. 规范文件后缀:MDX 文件标准后缀名为 .mdx。
  3. 分段留空:段落与段落、段落与代码块或表格之间保留一个完整的空行。
  4. 组件交互:在 MDX 中,你还可以直接使用 import 导入并使用 React/Vue 组件。

Footnotes

  1. 这是脚注的具体解释内容。 ↩