Markdown 使用

2026-10-31 16:541 次阅读

面向初学者与日常写作者的 Markdown 语法手册。

Markdown 使用教程

> 面向初学者与日常写作者的 Markdown 语法手册。
> 涵盖基础语法、扩展语法、Obsidian 专用写法以及常见问题排查。

1.Markdown简介

Markdown 是一种轻量级标记语言，由 John Gruber 在 2004 年创建。它用纯文本加少量符号来表达格式，文件是 .md 后缀，任何文本编辑器都能打开。

它的核心特点：

纯文本：不依赖特定软件，几十年后依然可读
易读易写：源文件本身就接近排版后的样子
可转换：能转成 HTML、PDF、Word、幻灯片等格式
版本友好：适合 Git 管理，便于对比差异

常见的使用场景：

场景	说明
个人笔记	Obsidian、Typora 等本地笔记工具
项目文档	README、CHANGELOG、接口文档
博客写作	静态站点生成器（Hexo、Hugo）
协作平台	GitHub、GitLab、语雀、飞书文档
技术出版	电子书、课程讲义、幻灯片

1.1方言说明

Markdown 没有唯一标准，常见方言有：

方言	特点
CommonMark	最严格的通用规范，多数解析器兼容
GFM (GitHub Flavored Markdown)	增加表格、任务列表、删除线、自动链接
Obsidian Flavored Markdown	在 GFM 基础上增加双链、块引用、Callout、公式

> 📌 本文以 GFM + Obsidian 两种环境都能正常渲染为目标编写。遇到平台差异时会单独标注。

2.工具与环境

工具	平台	特点
Obsidian	Win / macOS / Linux / 移动端	本地优先，双链与图谱强大，适合知识库
Typora	Win / macOS / Linux	所见即所得，写作体验流畅
VS Code	全平台	配合插件可预览、可导出，适合写代码文档
GitHub / GitLab	网页	仓库内自动渲染 README 与文档
语雀 / 飞书	网页	团队协作，支持大部分 GFM 语法

写文件时的三个基本要求：

文件后缀用 .md（少数平台也认 .markdown）
编码统一使用 UTF-8，避免中文乱码
段落之间留一个空行，这是 Markdown 最重要的排版习惯

3.基础语法

3.1标题

用 # 表示标题，一级标题 1 个 #，最多到六级：

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

各级标题的层级关系：

写法	层级	典型用途
`#`	一级	文章标题，全文只用一个
`##`	二级	主要章节
`###`	三级	章节下的小节
`####` 及以下	四级至六级	更细的划分，尽量少用

要点：

# 后面建议加一个空格，兼容性最好
一篇文章通常只用一个一级标题（文章标题）
不要跳级使用（比如从 ## 直接到 ####），方便生成目录

另一种写法是 Setext 风格（仅支持一到二级），用下划线表示：

一级标题
========

二级标题
--------

> ⚠️ 这种写法容易和分隔线、列表混淆，日常不推荐。

3.2段落与换行

段落：连续的文字算一段，段落之间用空行分隔。直接回车换行在多数渲染器里会被合并成同一段。

这是第一段。
这行仍然属于第一段。

这是第二段。

段内换行有三种方式：

方式	写法	说明
行尾两个空格	`文字␣␣` + 回车	最通用，但空格看不见
行尾反斜杠	`文字\` + 回车	直观，GFM 支持
HTML 换行标签	`<br>`	兼容性最好，但不够“纯 Markdown”

第一行结尾加两个空格  
第二行

3.3强调

*斜体* 或 _斜体_
**粗体** 或 __粗体__
***粗斜体***
~~删除线~~

效果：斜体、粗体、粗斜体、删除线

注意：

强调符号紧贴文字，不要写成 * 斜体 *
中文里用 _ 容易在词中间失效，推荐统一用 *
删除线属于 GFM 扩展，极少数老解析器不支持

3.4分隔线

单独一行写三个或更多的 -、*、_：

---

***

___

效果：

要点：分隔线前后各留一个空行，否则可能被当成二级标题（Setext）或列表的一部分。

4.列表

4.1无序列表

用 -、*、+ 开头，后面跟一个空格：

- 苹果
- 香蕉
- 橙子

效果：

苹果
香蕉
橙子

> 📌 同一篇文档里统一用一种符号，混用虽然能渲染，但不利于后续维护。

4.2有序列表

用数字加点开头：

1. 准备食材
2. 处理食材
3. 下锅烹饪

效果：

准备食材
处理食材
下锅烹饪

关键点：后续编号写什么数字都不影响渲染，解析器会自动按顺序编号。所以下面这种写法渲染结果和上面完全一样：

1. 准备食材
1. 处理食材
1. 下锅烹饪

这种写法在增删条目时不用重新编号，是被广泛推荐的写法。但如果你需要从指定数字开始（比如从 3 开始），就必须显式写第一个数字：

3. 第三步
4. 第四步

4.3嵌套列表

子列表用 2 个或 4 个空格缩进（推荐 4 个空格或与父级内容对齐的 Tab）：

- 前端
    - HTML
    - CSS
    - JavaScript
- 后端
    1. Node.js
    2. Python

效果：

前端
- HTML
- CSS
- JavaScript
后端
1. Node.js
2. Python

常见坑：缩进不足会被当成同级；缩进过多可能被当成代码块（4 空格缩进在部分解析器里等于代码块，Obsidian 中只要紧跟在列表项后就没问题）。

4.4任务列表

GFM 扩展语法，用 - [ ] 表示未完成，- [x] 表示已完成：

- [x] 完成需求评审
- [x] 编写接口文档
- [ ] 联调测试
- [ ] 上线发布

效果：

完成需求评审
编写接口文档
联调测试
上线发布

在 Obsidian 里点击方框即可切换状态，是管理待办最轻量的方式。

5.链接与图片

5.1行内链接

[显示文字](https://example.com)
[带标题的链接](https://example.com "鼠标悬停显示的文字")

效果：显示文字

指向本文其他位置的写法见 11.2 标题锚点。

5.2自动链接

尖括号包裹网址或邮箱，会直接变成可点击链接：

效果：

GFM 还支持裸网址自动识别，如 https://example.com 直接写成文本也能点击。但中文语境下裸链接容易和标点粘连，推荐仍用尖括号。

5.3引用式链接

把网址集中放在文末，正文只写引用标识，适合长文或同一链接多次出现：

这是[官方文档][docs]的地址，也可以看[入门指南][docs]。

[docs]: https://example.com/docs "官方文档"

效果：这是官方文档的地址。

5.4图片

语法只比链接多一个感叹号：

![图片描述](https://example.com/pic.png)
![图片描述](./images/pic.png "图片标题")

要点：

图片描述 是替代文本，图片加载失败时显示，也利于无障碍阅读
路径支持相对路径、绝对路径、网络地址
Obsidian 中更常用 !图片名.png，见 11.3 块引用与嵌入

调整图片尺寸（GitHub 与部分平台支持 HTML 写法）：

<img src="./images/pic.png" width="300" alt="示意图">

6.引用

用 > 开头表示引用块：

&gt; 这是一段引用。
&gt; 引用可以有多行。
&gt;
&gt; 空一行后仍在同一个引用块内。

效果：

> 这是一段引用。
> 引用可以有多行。
>
> 空一行后仍在同一个引用块内。

引用可以嵌套，也可以容纳列表、代码等块级内容：

&gt; 外层引用
&gt; &gt; 嵌套引用
&gt;
&gt; - 引用中的列表
&gt; - 第二项
&gt;
&gt; ```js
&gt; console.log("引用中的代码");
&gt; ```

要点：

每行都要以 > 开头，空行也要写 >（或留空但保持缩进）
引用内的 Markdown 语法照常生效

7.代码

7.1行内代码

用一对反引号包裹：

使用 `npm install` 安装依赖。

效果：使用 npm install 安装依赖。

如果代码本身包含反引号，用双反引号包裹：

``代码里有 `反引号` 的情况``

7.2代码块

用三个反引号包裹，并在开头标注语言以启用高亮：

```javascript
function greet(name) {
  console.log(`Hello, ${name}`);
}
```

效果：

function greet(name) {
  console.log(`Hello, ${name}`);
}

常用语言标注：

标注	语言	标注	语言
`bash` / `shell`	Shell	`js` / `javascript`	JavaScript
`python`	Python	`ts` / `typescript`	TypeScript
`json`	JSON	`yaml` / `yml`	YAML
`html`	HTML	`css`	CSS
`sql`	SQL	`markdown` / `md`	Markdown
`java`	Java	`go`	Go
`c` / `cpp`	C / C++	`diff`	差异对比

不写语言标注也能渲染成代码块，但没有高亮。

7.3代码块中显示反引号

如果代码块内部本身包含三个反引号（比如你要教别人写代码块），外层要用四个反引号：

````markdown
```bash
echo "hello"
```
````

规则很简单：外层反引号数量 > 内层最多连续反引号数量。

8.表格

8.1基本语法

用 | 分隔单元格，第二行用 - 定义表头分隔线：

| 姓名 | 年龄 | 城市 |
| --- | --- | --- |
| 张三 | 25 | 北京 |
| 李四 | 30 | 上海 |

效果：

姓名	年龄	城市
张三	25	北京
李四	30	上海

要点：

表格前后必须有空行，否则不会渲染（最常见的报错原因）
第二行的分隔线不能省略
列数不必对齐，源文件丑一点不影响渲染

8.2对齐方式

在分隔线中加入冒号控制对齐：

| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |
| A | B | C |

效果：

左对齐	居中	右对齐
A	B	C

8.3单元格内的特殊内容

竖线转义：单元格内容里要写 |，用 \|：

| 运算符 | 含义 |
| --- | --- |
| `a \| b` | 按位或 |

单元格内换行：标准 Markdown 不支持，只能用 <br>：

| 项目 | 说明 |
| --- | --- |
| 安装 | 第一步<br>第二步 |

单元格内写代码：用反引号，但如果代码里同时有竖线，需要同时处理转义。

9.扩展语法

以下语法属于扩展，GFM 或 Obsidian 支持，但并非所有平台都认，跨平台发布时需注意。

9.1删除线

~~这段文字已作废~~

效果：这段文字已作废

9.2脚注

Markdown 由 John Gruber 创建[^1]。

[^1]: 官方站点：https://daringfireball.net/projects/markdown/

效果：Markdown 由 John Gruber 创建^1。

9.3上下标

标准 Markdown 没有上下标，用 HTML 标签实现：

H<sub>2</sub>O
x<sup>2</sup>

效果：H₂O、x²

9.4数学公式

Obsidian、Typora、GitHub 均支持 LaTeX 公式。行内用 $...$ ，独立成块用 $$...$$：

质能方程：$E = mc^2$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

效果：

质能方程：$E = mc^2$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

注意：$ 与公式之间不要留空格，中文环境里 $ 也可能触发意外解析，必要时用 \$ 转义。

9.5Mermaid图表

Obsidian、GitHub、Typora 支持用代码块直接画图：

```mermaid
graph TD
    A[开始] --&gt; B{条件判断}
    B --&gt;|是| C[执行操作]
    B --&gt;|否| D[结束]
    C --&gt; D
```

效果：

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

除了流程图（graph / flowchart），还支持时序图（sequenceDiagram）、甘特图（gantt）、类图（classDiagram）、饼图（pie）等。

9.6HTML混排

Markdown 允许直接嵌入 HTML，用于实现 Markdown 做不到的效果：

<details>
<summary>点击展开</summary>

这里是被折叠的内容。

</details>

效果：

点击展开

这里是被折叠的内容。

要点：

<details> 内部前后要留空行，否则内部 Markdown 不解析
出于安全考虑，GitHub 会过滤 script、style 等标签
不要滥用 HTML，会破坏纯文本可读性

9.7目录TOC

GitHub 会自动为标题生成锚点，但不会自动生成目录，需要手动写或借助工具。常见写法：

- [第一节](#第一节)
- [第二节](#第二节)

锚点规则各平台不同，是最容易踩坑的地方：

平台	锚点规则	示例（标题 `## 1. 环境要求`）
GitHub	转小写、去标点、空格转 `-`	`#1-环境要求`
Obsidian	标题原文，保留标点与空格	`#1. 环境要求`

> ⚠️ 在 Obsidian 中必须使用双链格式 [显示文字](#标题原文)，用 GitHub 风格锚点会跳转失败。详见 11.2 标题锚点。

10.转义字符

在 Markdown 中有特殊含义的符号，前面加反斜杠 \ 可以按字面显示：

\*不是斜体\*
\# 不是标题
\[不是链接\]
1\. 不是列表

可转义的字符包括：

\ ` * _ { } [ ] ( ) # + - . ! | > ~

常见使用场景：

写 C++、C# 这类词时通常无需转义，但如果出现在行首要注意
表格单元格内写竖线用 \|
行首写 2024. 这类年份时可能被识别成有序列表，写成 2024\.

11.Obsidian专用语法

Obsidian 在 GFM 基础上扩展了一套“知识库”语法，是本目录文档的主要查看环境。

11.1双向链接

用双方括号引用库内其他笔记：

另一篇笔记
显示为别的文字
[另一篇笔记](#某个标题)

要点：

链接的是文件名（不含 .md 后缀）
文件名重复时要写路径，如 文件夹/笔记名
被链接的笔记会自动出现在“反向链接”面板中

11.2标题锚点

跳转到本文某个标题，可写 [标题](#标题) 或 [显示文字](#标题)：

[段落与换行](#32段落与换行)
[11.Obsidian专用语法](#11obsidian专用语法)

关键规则：锚点必须是标题 ## 之后的原文，不能按 GitHub 规则转换。

标题写法	正确锚点	错误锚点
`## 1.Markdown简介`	`[1.Markdown简介](#1markdown简介)`	`[1-markdown简介](#1-markdown简介)`
`## 3.2段落与换行`	`[3.2段落与换行](#32段落与换行)`	`[32段落与换行](#32段落与换行)`
`## 六、Docker命令`	`[六、Docker命令](#六docker命令)`	`[六docker命令](#六docker命令)`

> ⚠️ 标题中不要出现 ASCII 空格。Obsidian 的 [别名](#锚点) 遇到标题里的空格时容易解析失败。推荐写成 ## 3.2段落与换行 这种连写形式，并在链接里用别名显示成 3.2 段落与换行。
>
> 本文所有标题均已按此规则处理，可直接作为模板参考。

11.3块引用与嵌入

块引用：在某个段落末尾写 ^块标识，就可以从别处精确引用这一段：

这句话很重要，需要被引用。 ^important-note

然后在其他笔记里引用：

[笔记名](#important-note)

嵌入：链接前加感叹号，把内容直接显示出来：

!另一篇笔记                嵌入整篇笔记
![另一篇笔记](#某个标题)        嵌入某个章节
!图片.png                  嵌入图片（可加尺寸：!300）
!文档.pdf                  嵌入 PDF

11.4标签

用 #标签 做横向分类，与文件夹的纵向结构互补：

#项目/进行中
#技术/前端/React
#待整理

要点：

标签不能包含空格，多层级用 / 分隔
与标题冲突：行首的 #标题 若后面没有空格可能被识别为标签，写标题时保持 # 后有空格
在搜索面板输入 tag:#项目 可筛选

11.5Callout提示块

用 > [!类型] 生成带颜色和图标的高亮块：

&gt; [!note] 说明
&gt; 这是一条补充说明。

&gt; [!warning] 注意
&gt; 这里容易出错。

&gt; [!tip]- 可折叠提示
&gt; 标题带减号表示默认折叠。

支持的常用类型：

类型	用途	类型	用途
`note`	普通说明	`tip`	技巧建议
`info`	信息	`warning`	警告
`danger`	危险操作	success	成功/完成
`question`	疑问	`quote`	引用
`example`	示例	`bug`	缺陷记录

可折叠写法：[!note]- 默认收起，[!note]+ 默认展开。

11.6YAML属性

文件最顶部用三条横线包裹 YAML，可定义标题、标签、别名等元数据：

---
title: Markdown 使用教程
tags:
  - 教程
  - 写作
aliases:
  - MD教程
created: 2026-10-21
---

这些属性会被 Obsidian 的搜索、别名跳转、模板插件读取。注意：

必须位于文件第一行，前面不能有空行
--- 前后不要缩进
如果文档不需要属性，可以完全不写

12.实战模板

12.1README模板

# 项目名称

一句话说明这个项目是做什么的。

## 功能特性

- 特性一
- 特性二

## 快速开始

```bash
git clone https://example.com/repo.git
cd repo
npm install
npm run dev
```

## 配置说明

| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| `PORT` | 服务端口 | `3000` |

## 目录结构

```text
src/
├── components/
├── pages/
└── utils/
```

## 许可证

MIT

12.2技术笔记模板

---
title: 主题名称
tags:
  - 技术
created: 2026-10-21
---

# 主题名称

## 背景与问题

为什么要记录这篇笔记。

## 核心结论

&gt; [!tip] 结论先行
&gt; 用两三句话把最重要的结论写在这里。

## 详细内容

### 原理

### 实践步骤

1. 第一步
2. 第二步

```bash
# 可执行的命令
```

### 踩坑记录

| 现象 | 原因 | 解决 |
| --- | --- | --- |
| 报错信息 | 原因分析 | 处理方式 |

## 参考资料

- [官方文档](https://example.com)

13.语法速查表

想要的效果	写法
标题	`# 一级` 到 `###### 六级`
粗体	`文字`
斜体	`文字`
粗斜体	`*文字*`
删除线	`~~文字~~`
分隔线	`---`
无序列表	`- 项目`
有序列表	`1. 项目`
任务列表	`- [ ] 待办` / `- [x] 完成`
行内代码	`code`
代码块	三个反引号 + 语言名
链接	`[文字](url)`
图片	`![描述](url)`
引用	`> 内容`
表格	`\| 表头 \|` + `\| --- \|`
脚注	`文字[^1]` + `[^1]: 内容`
公式	$公式$ / `$$公式$$`
换行	行尾两个空格或 `<br>`
转义	`\*`
Obsidian双链	`笔记名`
标题锚点	`[别名](#标题原文)`
嵌入	`!笔记名`
标签	`#分类/子类`
提示块	`> [!note] 标题`

14.常见问题

14.1表格不渲染

原因：表格前缺少空行，或第二行分隔线写错。

排查：确认表格上方有一个空行；确认第二行是 | --- | --- | 形式且列数与表头一致。

14.2回车换行不生效

原因：Markdown 把单个换行视为空格。

解决：行尾加两个空格、加 \，或使用 <br>。段落之间直接空一行最稳。

14.3有序列表编号乱掉

原因：列表中间插入了空行或非列表内容，导致列表被切断。

解决：保持列表连续；需要插入说明文字时，用两个以上空格缩进使其属于列表项。

14.4代码块里的内容被解析

原因：代码块用反引号包裹，但代码内部含有反引号。

解决：外层反引号数量大于内层，例如外层四个反引号包裹内层三个。

14.5图片不显示

原因：路径错误或大小写不一致。Windows 在资源管理器里不区分大小写，但 GitHub 等平台区分。

解决：使用相对路径 ./images/pic.png，并核对文件名大小写与扩展名。

14.6Obsidian目录点击无反应

原因：锚点用了 GitHub 的 slug 规则，或标题中含 ASCII 空格导致链接被截断。

解决：锚点改为标题原文，标题尽量去掉空格，并在链接里用别名控制显示效果。

14.7中文标点导致链接失效

原因：全角括号、全角冒号不能用于语法结构。

解决：语法符号一律用半角：()、:、|、#；中文标点只能出现在正文里。

14.8加粗在中文里不生效

原因：强调符号与文字之间有空格，或符号紧贴中文标点。

解决：写成 **加粗文字**，符号与文字之间不留空格。

>[! danger]- 说明
>初学者易范的错误！！

附：写作习惯建议

一屏能读完的段落：长段落拆短，Markdown 的可读性来自空行与列表
标题即大纲：写完先检查标题层级，能直接当目录用
少用花哨语法：Callout、折叠块、Mermaid 适度使用，过多会喧宾夺主
链接用相对路径：文档随仓库迁移时不至于全部失效
源文件也要可读：Markdown 的价值在于即使不渲染也看得懂