Markdown 语法详细教程(学习markdown，看这一篇就够了)

Markdown 语法详细教程

Markdown 是一种轻量级标记语言，用纯文本就能写出结构清晰、格式美观的文档，并可以方便地转换成 HTML、PDF 等格式。本教程主要以常用的 GitHub / VSCode / Gitee 等环境兼容的语法为主。

1. 标题（Heading）

语法：在行首使用 # 加空格，# 的个数表示标题级别（1--6 级）。

markdown 复制代码

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

注意点 ：
- # 后面推荐加一个空格，兼容性更好。
- 一级、二级标题通常用于文档结构的大纲，不要滥用。

2. 段落与换行

段落：普通文本直接写，中间空一行表示分段。
换行：行尾加两个空格，然后回车，或者使用 <br>。

markdown 复制代码

这是一段文字。  
这一句与上一句之间是"换行"，不是新段落。

这是新的一段（中间空了一行）。

3. 字体样式

粗体：**加粗内容** 或 __加粗内容__
斜体：*斜体内容* 或 _斜体内容_
粗斜体 ：***粗斜体内容***
~~删除线~~ ：~~删除的内容~~
下划线（不是标准 Markdown，但很多渲染器支持 HTML）：<u>带下划线的文本</u>

markdown 复制代码

这是 **加粗** 的文字。
这是 *斜体* 的文字。
这是 ***粗斜体*** 的文字。
这是 ~~删除线~~ 效果。
这是 <u>下划线</u> 效果。

4. 列表（有序 / 无序 / 嵌套）

4.1 无序列表

语法：以 -、* 或 + 加空格开头，效果相同，推荐统一使用 -。

markdown 复制代码

- 无序项 1
- 无序项 2
  - 子项 2.1
  - 子项 2.2

4.2 有序列表

语法：使用数字加点加空格，如 1. 。

markdown 复制代码

1. 有序项 1
2. 有序项 2
3. 有序项 3

数字顺序在大多数渲染器中可自动纠正，但建议写真实顺序，方便阅读和 diff。

4.3 混合 / 嵌套列表示例

markdown 复制代码

1. 一级有序
   - 嵌套无序 1
   - 嵌套无序 2
2. 第二项
   1. 内部有序 2.1
   2. 内部有序 2.2

注意：嵌套列表需要缩进两个或四个空格（或一个制表符），通常推荐两个空格或四个空格保持风格统一。

5. 引用（Blockquote）

语法：在行首使用 >（大于号）加空格。

markdown 复制代码

> 这是一段引用文字。
> 可以换行继续写，仍然属于同一个引用。

> 也可以
>> 嵌套引用（两层）

引用内可以包含标题、列表、代码块等，常用于引用他人观点、提示信息等。

6. 代码与代码块

6.1 行内代码（Inline Code）

语法：使用一个反引号 `（键盘上 1 左边）包裹。

markdown 复制代码

请执行 `npm install` 命令。
变量名为 `userName`。

6.2 代码块（Code Block）

语法 1（推荐）：使用三个反引号包裹，多数平台支持高亮。

markdown 复制代码

```javascript
function hello(name) {
  console.log('Hello ' + name);
}
hello('world');

markdown 复制代码

> 上面示例中，外层是为了演示的 Markdown，实际写代码时不要嵌套两层反引号，可以换成其他语言标识。

- **常见语言标识**：
  - `bash` / `shell`
  - `javascript` / `js`
  - `typescript` / `ts`
  - `html` / `css` / `json` / `yaml` 等

### 6.3 缩进式代码块（不推荐）

- 在每行前缩进 4 个空格或 1 个 Tab，会被解析为代码块。由于不够直观且容易与列表嵌套冲突，**一般不推荐使用**。

---

## 7. 链接与图片

### 7.1 链接（Link）

- **语法**：`[显示文本](链接地址 "可选的标题")`

```markdown
[跳转到 Gitee](https://gitee.com "Gitee 官网")
[本仓库 README](./README.md)

7.2 图片（Image）

语法：在链接前加一个 !

markdown 复制代码

![描述文本](https://example.com/logo.png "可选的标题")

注意点 ：
- 描述文本用于图片加载失败时的占位，同时也利于无障碍阅读。
- 建议使用相对路径 引用仓库内图片，例如：./images/xxx.png。

8. 表格（Table）

基础语法：

markdown 复制代码

| 列 1 | 列 2 | 列 3 |
| ---- | :--- | ---: |
| 居中 | 左对齐 | 右对齐 |
| A    | B    | C    |

第二行用于定义对齐方式：
- ---：默认（左对齐或居中，视渲染器而定）。
- :---：左对齐。
- :---:：居中对齐。
- ---:：右对齐。
建议使用表格时：
- 保持列数一致。
- 适当对齐空格，提升源码可读性（不是必须）。

9. 分割线（Horizontal Rule）

语法：在单独一行中连续三个及以上的 -、* 或 _，中间可以有空格。

markdown 复制代码

---

***

___

分割线用于在视觉上分隔章节，不必过多使用。

10. 转义字符（Escape）

有时我们希望显示 Markdown 语法本身，而不是让它被解析，这时可以使用反斜杠 \ 进行转义。

常见可转义字符：\*、\_、\#、\、\[、\]、\(、\) 等。

markdown 复制代码

这是一个星号：\* 不会被解析为列表或斜体。

11. 任务列表（Task List）

许多平台（GitHub、Gitee、部分文档系统）对任务列表提供原生支持。

markdown 复制代码

- [ ] 待办事项 1
- [x] 已完成事项 2
  - [ ] 子任务 2.1

- [ ] 表示未完成。
- [x] 表示已完成。

12. 目录（TOC）与锚点

Markdown 本身不强制内置目录语法，但很多渲染引擎会根据标题自动生成目录。

推荐做法：
1. 合理设计标题层级（##、###）。
2. 使用文档系统/平台的"自动目录"功能（如某些 Markdown 编辑器、文档平台）。
有些平台支持使用 [TOC] 或类似标记自动生成目录，但兼容性依赖具体平台。

13. 内联 HTML

在大多数 Markdown 渲染器中，可以直接嵌入少量 HTML 以增强展示能力，比如：

markdown 复制代码

<details>
  <summary>展开/收起示例</summary>

  这里是折叠内容。

</details>

使用内联 HTML 时要注意：
- 有些平台会限制或过滤特定 HTML 标签。
- 建议只在 Markdown 语法难以实现效果时再使用。

14. 常见写作规范与建议

标题层级清晰：不要只用一个级别的标题，合理划分章节。
列表前后空行：在复杂嵌套时，适当空行让源码更清晰。
中英文之间留空格 ：例如：在 VSCode 中编写 Markdown。
链接与图片使用相对路径：方便仓库内移动与迁移。
长文档拆分 ：当单文件过长时，可以拆分成多个 .md 文件，通过链接互相引用。

示例：

markdown 复制代码

> 提示：在编写技术文档时，尽量让示例代码可以直接复制运行。

15. 实战示例：一个小型文档骨架

markdown 复制代码

## 项目介绍

简单介绍项目的背景与目标。

## 快速上手

1. 安装依赖：
   ```bash
   npm install

启动项目：
bash 复制代码
```
npm run dev
```

功能说明

功能 A：简单描述。
功能 B：简单描述。

常见问题

问题 1：......
问题 2：......

yaml 复制代码

---

## 16. 图表与可视化（流程图 / 时序图 / 饼图等）

很多现代文档平台都在 Markdown 的基础上扩展了"图表语法"，最常见的是 **Mermaid 图表**，支持流程图、时序图、甘特图、饼图等。下面以 Mermaid 为例说明常见用法（GitHub、Gitee、部分知识库系统等都支持）。

> 注意：是否支持 Mermaid、支持到什么版本，取决于**具体平台**。在不支持的环境中，会被当作普通代码块显示。

### 16.1 Mermaid 基本写法

- **语法**：代码块语言标识使用 `mermaid`，内部写对应的图表描述。

```markdown
```mermaid
graph LR
  A[开始] --> B{条件判断}
  B -->|是| C[处理 1]
  B -->|否| D[处理 2]
  C --> E[结束]
  D --> E

yaml 复制代码

若所在平台支持 Mermaid，则会渲染为可视化流程图；否则会以代码形式展示。

---

### 16.2 流程图（Flowchart）

Mermaid 流程图的基本语法：

```markdown
```mermaid
graph TD
  Start([开始]) --> Input[输入数据]
  Input --> Process[处理逻辑]
  Process --> Decision{条件?}
  Decision -- 是 --> Branch1[分支 1]
  Decision -- 否 --> Branch2[分支 2]
  Branch1 --> End([结束])
  Branch2 --> End

javascript 复制代码

- `graph TD`：表示从上到下（Top-Down）布局；`LR` 表示从左到右（Left-Right）。
- 方括号 `[]`、大括号 `{}`、圆括号 `()` 可以表示不同样式的节点（具体样式由 Mermaid 渲染）。
- 使用 `-->` / `---` 表示箭头或连线，可以添加 `|文字|` 标注条件说明。

---

### 16.3 时序图（Sequence Diagram）

用于描述多个参与者之间随时间推移的调用关系。

```markdown
```mermaid
sequenceDiagram
  participant User as 用户
  participant FE as 前端
  participant BE as 后端

  User->>FE: 点击"登录"按钮
  FE->>BE: 发送登录请求
  BE-->>FE: 返回登录结果
  FE-->>User: 展示成功/失败提示

yaml 复制代码

- `participant` 定义参与者。
- `->>` / `-->>` 表示不同风格的箭头，用于区分同步/异步、请求/响应等。

---

### 16.4 甘特图（Gantt Chart）

用于展示任务与时间规划。

```markdown
```mermaid
gantt
  dateFormat  YYYY-MM-DD
  title 项目开发计划

  section 需求阶段
  需求分析       :a1, 2025-01-01, 5d

  section 开发阶段
  前端开发       :a2, after a1, 10d
  后端开发       :a3, after a1, 10d

  section 测试阶段
  联调与测试     :a4, after a2, 7d

perl 复制代码

- `dateFormat`：时间格式。
- `section`：分组标题。
- 每一行定义一个任务：`任务名 :id, 起始时间/依赖, 持续时间`。

---

### 16.5 饼图（Pie Chart）

用于展示占比关系。

```markdown
```mermaid
pie showData
  title 浏览器占比示意
  "Chrome" : 63
  "Safari" : 19
  "Firefox" : 4
  "Edge" : 7
  "其他" : 7

markdown 复制代码

- `pie showData`：开启饼图并展示数值。
- 每一行 `"名称" : 数值` 表示一块区域。

---

### 16.6 类图 / ER 图 / 状态图（简单了解）

Mermaid 还支持：

- **类图（classDiagram）**：表示类之间继承、关联关系。
- **状态图（stateDiagram）**：表示状态机的状态迁移。
- **实体关系图（erDiagram）**：表示数据表之间的关系。

示例（类图）：

```markdown
```mermaid
classDiagram
  class User {
    +string name
    +login()
  }
  class Admin {
    +lockUser()
  }
  User <|-- Admin

yaml 复制代码

在需要说明系统设计、对象关系等时，这类图非常有用。

---

### 16.7 通过图片插入图表

如果目标平台**不支持 Mermaid** 或你更习惯用专业工具（如 Excel、PowerPoint、ProcessOn、draw.io、XMind 等）绘图，可以：

1. 在外部工具中画好图表（柱状图、折线图、思维导图等）。
2. 导出为 `png` / `jpg` / `svg` 等图片文件，放到仓库内，例如 `images/xxx.png`。
3. 使用 Markdown 图片语法插入：

```markdown
![项目架构图](./images/project-architecture.png "项目整体架构")

优点：渲染效果统一，适用于任何支持图片的 Markdown 渲染器。
缺点：图表内容不易在 Markdown 内直接修改。

16.8 使用表格模拟简单数据图表

对于一些简单的数据对比，可以直接使用表格展示，既兼容又清晰：

markdown 复制代码

| 时间      | 访问量 | 备注         |
| --------- | -----: | ------------ |
| 2025-01-01 |  1200 | 新版本上线   |
| 2025-01-02 |  980  |              |
| 2025-01-03 |  1500 | 推广活动开始 |

如需真正的统计图（折线/柱状/饼图），可以：

在文档中贴表格 + 分析文字；
或者配合外部工具生成图片后插入。

17. 在本仓库中的使用建议

结合当前仓库性质（记录项目开发经验、笔记等），建议：

新建专题文档时，统一使用 xxx笔记.md、xxx总结.md 或类似命名。
每篇文档中：
- 开头使用 ## 标题作为文档名。
- 使用 ### 作为第二层级（如"背景"、"步骤"、"问题记录"）。
- 使用列表和代码块详细记录操作步骤与命令。
若文档较长，可在开头手工写一个简单目录：

markdown 复制代码

## 目录
- [背景](#背景)
- [操作步骤](#操作步骤)
- [问题排查](#问题排查)

以上就是一份比较全面的 Markdown 语法与使用指南，后续写文档遇到不熟悉的格式时，可以随时回来看示例。