Markdown 文件写法学习文档

核对时间：2026-07-09
适合人群：需要编写 README、学习文档、接口文档、项目说明、周报、技术方案和知识库文档的人。
学习目标：掌握 Markdown 基础语法、GitHub Flavored Markdown 扩展、文档组织方法、常见陷阱和可复用模板。
资料依据：CommonMark 官方规范、GitHub Flavored Markdown 规范、GitHub Docs 写作语法说明。

Markdown 是什么
Markdown、CommonMark 与 GFM 的关系
文件与编辑环境
基础语法
GitHub Flavored Markdown 扩展
图片、相对路径与资源管理
代码块、嵌套代码块与语法高亮
HTML、转义与兼容性
目录、锚点与长文档结构
常见文档模板
写作规范与排版建议
常见错误与排查
工具链建议
学习检查题
官方资料

1. Markdown 是什么

Markdown 是一种轻量级标记语言。它用纯文本符号表达标题、列表、链接、图片、代码块、引用、表格等结构，再由 Markdown 渲染器转换成 HTML 或其他格式。

你写的是：

markdown

# 项目说明

这是一个前端项目。

- 支持 Vue
- 支持 TypeScript
- 支持 Vite

渲染后看到的是：

项目说明

这是一个前端项目。

支持 Vue
支持 TypeScript
支持 Vite

Markdown 的优势：

文件是纯文本，适合 Git 版本管理。
语法少，学习成本低。
很适合写 README、学习笔记、接口说明、技术方案。
GitHub、GitLab、VS Code、Obsidian、Notion、语雀等都支持 Markdown 或类似语法。

Markdown 的限制：

不同平台支持的扩展不同。
表格、复杂布局、分页排版能力不如 Word。
有些语法在 GitHub 能渲染，在其他平台不一定能渲染。

2. Markdown、CommonMark 与 GFM 的关系

2.1 Markdown

Markdown 最早是 John Gruber 设计的一套轻量文本格式。它简单易写，但早期规范不够严格，不同解析器对边界情况的处理可能不同。

2.2 CommonMark

CommonMark 是对 Markdown 的标准化规范，目标是让语法解析更明确、更一致。本文档里的基础语法优先按 CommonMark 理解。

2.3 GitHub Flavored Markdown

GitHub Flavored Markdown，简称 GFM，是 GitHub 在 CommonMark 基础上增加的一组扩展，常见包括：

表格。
任务列表。
删除线。
自动链接。
GitHub 上的 issue、PR、用户引用等平台能力。

2.4 实际写作建议

如果你要写通用 Markdown：

优先使用 CommonMark 基础语法。
少用平台专属扩展。
表格、任务列表、删除线可以视为常见 GFM 扩展。

如果你主要在 GitHub / GitLab / 代码仓库中写文档：

可以使用 GFM。
README、PR 描述、Issue 模板、技术文档都很适合 GFM。

3. 文件与编辑环境

3.1 文件扩展名

常见扩展名：

扩展名	用途
`.md`	最常见 Markdown 文件
`.markdown`	也可用，但没有 `.md` 常见
`.mdx`	Markdown + JSX，常用于 React 文档站

建议普通文档统一使用 .md。

3.2 文件编码

建议统一使用 UTF-8。

原因：

中文不容易乱码。
GitHub、VS Code、现代构建工具默认支持好。
跨平台兼容性更稳定。

3.3 常用编辑器

工具	适合场景
VS Code	项目文档、README、技术文档
Obsidian	个人知识库
Typora	所见即所得写作
GitHub Web 编辑器	轻量修改 README、Issue
VitePress / MkDocs / Docusaurus	文档站

3.4 VS Code 常用能力

Markdown 预览：Ctrl + Shift + V
侧边预览：Ctrl + K V
安装 markdownlint 扩展检查格式。
安装 Prettier 格式化 Markdown。

3.5 Frontmatter（YAML 头）

很多静态站点生成器（VitePress、Hugo、Jekyll、Obsidian、Hexo）会读取文件最顶部的 YAML 元数据块，这叫做 Frontmatter：

markdown

---
title: Vite 配置指南
author: Alice
date: 2026-07-09
tags:
  - vite
  - frontend
---

# Vite 配置指南

要点：

Frontmatter 必须在文件最顶部，用 --- 开始和结束。
里面是 YAML 语法，键值对、列表、嵌套都支持。
不同工具的字段名不同：VitePress 用 title、description；Hugo 用 title、date、draft；Obsidian 用 tags、aliases。

⚠️ 第 4.9 节提到「文件顶部的 --- 可能被当作 Frontmatter」：如果文档第一行就是 ---，渲染器可能把它当成 Frontmatter 而隐藏。普通 README 里不要在第一行放分隔线，要么前面加内容，要么换用别的分隔方式。

Frontmatter 是否渲染、字段含义完全取决于目标工具，不是 CommonMark 标准的一部分。

4. 基础语法

4.1 标题

Markdown 使用 # 表示标题层级。

markdown

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

建议：

一个文档只使用一个一级标题。
章节从二级标题开始。
不要跳级，例如从 ## 直接跳到 ####。
# 后面保留一个空格。

4.2 段落

段落之间用空行分隔。

markdown

这是第一段。

这是第二段。

不要用多个空格硬凑段落。Markdown 中换行和段落不是一回事。

4.3 换行

普通换行不一定渲染成 <br>。如果确实需要硬换行，可以：

markdown

第一行  
第二行

上面第一行末尾有两个空格。

更清晰的做法是直接拆成段落：

markdown

第一段。

第二段。

4.4 粗体、斜体、删除线

markdown

**粗体**

*斜体*

***粗斜体***

~~删除线~~

效果：

粗体

斜体

粗斜体

~~删除线~~

注意：删除线属于 GFM 扩展，不是所有 Markdown 渲染器都支持。

4.5 无序列表

markdown

- JavaScript
- TypeScript
- Vue

效果：

JavaScript
TypeScript
Vue

建议统一使用 -，不要在一个文档里混用 -、*、+。

4.6 有序列表

markdown

1. 安装依赖
2. 启动项目
3. 构建项目

效果：

安装依赖
启动项目
构建项目

Markdown 通常会自动编号，因此你也可以写：

markdown

1. 安装依赖
1. 启动项目
1. 构建项目

但是为了源码可读性，学习文档建议保持真实编号。

4.7 嵌套列表

markdown

- 前端
  - JavaScript
  - TypeScript
- 后端
  - Node.js
  - Java

效果：

前端
- JavaScript
- TypeScript
后端
- Node.js
- Java

建议：

嵌套层级不要太深。
每层缩进通常用两个空格或四个空格，团队内保持一致。

4.8 引用

markdown

> 这是一段引用。
> 可以有多行。

效果：

这是一段引用。可以有多行。

引用里可以放其他 Markdown：

markdown

> **注意**
>
> - 不要把密钥写进前端环境变量。
> - 不要提交 `.env.local`。

4.9 分割线

markdown

---

效果：

常用 --- 分隔大章节。注意如果它出现在文件顶部，某些工具可能把它当作 Frontmatter 的开始。

4.10 行内代码

markdown

使用 `npm run dev` 启动项目。

效果：

使用 npm run dev 启动项目。

适合：

命令。
文件名。
变量名。
配置项。
API 名称。

4.11 代码块

使用三个反引号或三个波浪线包裹代码块。

markdown

```javascript
function add(a, b) {
  return a + b;
}
```

效果：

javascript

function add(a, b) {
  return a + b;
}

建议写语言名，方便语法高亮：

语言名	用途
`javascript`	JS
`typescript`	TS
`bash`	Shell 命令
`json`	JSON
`html`	HTML
`css`	CSS
`vue`	Vue SFC
`markdown`	Markdown 示例

4.12 链接

行内链接：

markdown

[MDN JavaScript](https://developer.mozilla.org/)

效果：

MDN JavaScript

引用式链接：

markdown

阅读 [CommonMark][commonmark] 规范。

[commonmark]: https://spec.commonmark.org/current/

适合一篇文章中多次引用同一个链接。

4.13 图片

markdown

![图片说明](./images/demo.png)

语法比链接多一个 !。

建议：

[] 中写有意义的替代文本。
不要写 ![image] 这种无意义 alt。
图片路径尽量使用相对路径，方便仓库迁移。

4.14 转义字符

如果想显示 Markdown 特殊符号本身，可以用反斜杠转义。

markdown

\*这不是斜体\*

\# 这不是标题

效果：

*这不是斜体*

# 这不是标题

常见需要转义的字符：

text

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

4.15 内联 HTML

很多 Markdown 渲染器支持内联 HTML。

markdown

<kbd>Ctrl</kbd> + <kbd>S</kbd>

效果：

注意：

GitHub 会过滤不安全 HTML。
不同平台对 HTML 支持不同。
能用 Markdown 解决时，不要优先写 HTML。

4.16 列表嵌套的精确缩进规则

CommonMark 规定：嵌套列表子项要与父项「标记后的第一个字符」对齐。父项标记（- 、1. 、* ）后面的内容从哪个列开始，子项就缩进到哪个列。

markdown

- 父项
  - 子项（两个空格，对齐「父项」的「父」字位置）

实际就是「- 占两列，所以子项缩进两列」。更长的有序列表标记要对应更多缩进：

markdown

10. 第十项
    - 子项（四个空格，因为 "10. " 占四列）

⚠️ 这是最容易渲染错的地方：

缩进不够：子项会被当成独立列表，破坏层级。
缩进太随意（有时两格有时四格）：视觉上似乎对齐，但解析器按列对齐，可能把内容拆散。

建议：统一用两个空格表示一级缩进，遇到两位数的有序列表时手动对齐到内容列。用 markdownlint 可以自动检查这类问题。

5. GitHub Flavored Markdown 扩展

5.1 表格

markdown

| 命令 | 说明 |
| --- | --- |
| `npm install` | 安装依赖 |
| `npm run dev` | 启动开发服务器 |
| `npm run build` | 构建生产产物 |

效果：

命令	说明
`npm install`	安装依赖
`npm run dev`	启动开发服务器
`npm run build`	构建生产产物

对齐：

markdown

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

效果：

左对齐	居中	右对齐
A	B	C

表格建议：

表格不要过宽。
单元格中可以使用行内代码、链接、粗体。
单元格中如果要显示 |，通常需要转义成 \|。

5.2 任务列表

markdown

- [x] 完成需求分析
- [ ] 编写代码
- [ ] 补充测试

效果：

[x] 完成需求分析
[ ] 编写代码
[ ] 补充测试

注意：

[x] 表示完成。
[ ] 中间必须有空格。
在 GitHub Issue / PR 中，任务列表可以交互勾选。

5.3 删除线

markdown

~~这个方案已废弃~~

效果：

~~这个方案已废弃~~

5.4 自动链接

在 GitHub 中，URL 通常会自动变成链接：

markdown

https://github.com

为了通用性，正式文档更推荐显式写成：

markdown

[GitHub](https://github.com)

5.5 脚注

GitHub 支持脚注：

markdown

这句话需要补充说明。[^note]

[^note]: 这是脚注内容。

效果在支持脚注的平台中会显示为可跳转注释。

注意：脚注不是所有 Markdown 渲染器都支持。

5.6 警告块和提示块

GitHub 支持特殊提示块：

markdown

> [!NOTE]
> 这是普通提示。

> [!WARNING]
> 这是警告。

注意：这是 GitHub 平台扩展，不属于 CommonMark 通用语法。

5.7 Mermaid 图

GitHub、很多文档站和部分编辑器支持 Mermaid。

markdown

```mermaid
flowchart TD
  A[开始] --> B[编写 Markdown]
  B --> C[预览]
  C --> D[提交]
```

适合画：

流程图。
时序图。
状态机。
架构关系。

注意：不是所有 Markdown 渲染器都支持 Mermaid。

5.8 数学公式

部分平台支持 LaTeX 风格公式。

markdown

行内公式：$a^2 + b^2 = c^2$

块级公式：

$$
E = mc^2
$$

注意：GitHub 支持数学表达式，但其他平台可能需要插件。

6. 图片、相对路径与资源管理

6.1 推荐目录结构

text

docs/
├── README.md
├── markdown-guide.md
└── images/
    ├── markdown-preview.png
    └── architecture.png

在 markdown-guide.md 中引用图片：

markdown

![Markdown 预览](./images/markdown-preview.png)

6.2 相对路径与绝对路径

相对路径：

markdown

[查看配置说明](./config.md)

绝对 URL：

markdown

[CommonMark](https://spec.commonmark.org/current/)

建议：

仓库内部文档用相对路径。
外部资料用完整 URL。
避免使用本机绝对路径，例如 C:\Users\...，别人无法访问。

6.3 图片 alt 文本

不推荐：

markdown

![image](./images/login.png)

推荐：

markdown

![登录页表单校验失败提示](./images/login-validation-error.png)

alt 文本的作用：

图片加载失败时仍能知道含义。
帮助读屏器理解图片。
让文档更容易维护。

6.4 图片大小

标准 Markdown 没有统一的图片尺寸语法。可以使用 HTML：

html

<img src="./images/logo.png" alt="项目 Logo" width="240">

注意：不同平台可能会过滤或限制 HTML 属性。

7. 代码块、嵌套代码块与语法高亮

7.1 代码块语言名

推荐写法：

markdown

```typescript
type User = {
  id: number;
  name: string;
};
```

不要写成：

markdown

```
type User = {
  id: number;
  name: string;
};
```

原因：没有语言名时，语法高亮和阅读体验会差一些。

7.2 展示 Markdown 代码块

如果你要在 Markdown 文档中展示 Markdown 代码块，可以用四个反引号包住三个反引号。

markdown

````markdown
```javascript
console.log("hello");
```
````

也可以使用波浪线 fence：

markdown

```javascript
console.log("hello");
```

CommonMark 允许使用三个或更多反引号，也允许使用三个或更多波浪线。反引号和波浪线不能混用。

7.3 列表中的代码块

列表中的代码块要缩进，或者放在列表项后并保持结构清晰。

markdown

1. 安装依赖：

   ```bash
   npm install

启动项目：
bash
```
npm run dev
```
1


很多渲染问题都来自列表和代码块缩进不一致。

### 7.4 代码块中放命令

命令推荐使用 `bash`：

```bash
npm install
npm run dev

不建议把命令提示符写进去：

bash

$ npm install

除非你明确要表达这是终端输入。否则用户复制时还要删掉 $。

8. HTML、转义与兼容性

8.1 Markdown 中能写 HTML 吗

多数 Markdown 渲染器允许写一部分 HTML。

markdown

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

这里是折叠内容。

</details>

GitHub 支持 details/summary，常用于折叠长内容。

8.2 什么时候不建议写 HTML

不建议为了普通排版大量写 HTML：

html

<h2>标题</h2>
<ul>
  <li>列表项</li>
</ul>

更推荐：

markdown

## 标题

- 列表项

原因：

Markdown 更易读。
更适合 Git diff。
更容易跨平台渲染。

8.3 HTML 与 Markdown 混写的坑

在一些 HTML 块内部，Markdown 可能不会继续被解析。

markdown

<div>

**这里是否会变粗，取决于渲染器。**

</div>

如果你要跨平台，尽量减少复杂 HTML 混写。

8.4 特殊字符

常见 HTML 实体：

字符	实体
`<`	`<`
`>`	`>`
`&`	`&`
`"`	`"`

示例：

markdown

HTML 标签写作 `&lt;div&gt;`。

9. 目录、锚点与长文档结构

9.1 手写目录

markdown

## 目录

1. [安装](#安装)
2. [配置](#配置)
3. [常见问题](#常见问题)

标题：

markdown

## 安装

## 配置

## 常见问题

9.2 GitHub 标题锚点规则

GitHub 会根据标题自动生成锚点。通常规则是：

转小写。
空格变成 -。
去掉多数标点。
重名标题会追加 -1、-2。

例如：

markdown

## Vite 配置

链接通常是：

markdown

[Vite 配置](#vite-配置)

中文标题在 GitHub 中可以正常生成锚点，但不同平台规则可能不同。

9.3 长文档推荐结构

markdown

# 文档标题

> 一句话说明文档目标。

## 目录

1. [背景](#1-背景)
2. [快速开始](#2-快速开始)
3. [核心概念](#3-核心概念)
4. [配置说明](#4-配置说明)
5. [常见问题](#5-常见问题)
6. [参考资料](#6-参考资料)

## 1. 背景

## 2. 快速开始

## 3. 核心概念

## 4. 配置说明

## 5. 常见问题

## 6. 参考资料

建议：

长文档一定要有目录。
标题编号可以帮助阅读和引用。
每章开头先说目的，再展开细节。

9.4 GitHub 锚点生成算法（精确规则）

第 9.2 节讲了大致规则，这里补 GitHub 的精确算法，方便手写稳定的目录链接。

GitHub 生成锚点时对标题做以下处理（依据 GitHub 的 slug 规则）：

转小写。
去掉标点符号（.、,、:、(、)、?、!、@、# 等），但保留中文、数字、字母、下划线。
空格换成 -。
连续的 - 合并为一个。
重名标题依次追加 -1、-2。

例如：

markdown

## Hello, World! (入门)

锚点形如 hello-world-入门（!、, 被去掉，空格换成 -，中文保留）。

⚠️ 注意事项：

不同平台（GitHub、GitLab、VS Code、VitePress）的 slug 规则不一致，手写锚点前先在该平台实测。
标题里如果有 emoji、特殊符号，锚点可能和预期不同。
更稳妥的做法：给标题配 HTML 显式锚点，或直接用文档站自动生成的目录，而不是手写。

手写目录时，中文标题的锚点直接「转小写 + 空格换 - + 去标点」通常能命中 GitHub 规则，但务必点一下链接验证。

10. 常见文档模板

10.1 README 模板

markdown

# 项目名称

一句话说明项目解决什么问题。

## 功能特性

- 功能一
- 功能二
- 功能三

## 技术栈

- Vue 3
- TypeScript
- Vite

## 快速开始

```bash
npm install
npm run dev

常用命令

命令	说明
`npm run dev`	启动开发服务器
`npm run build`	构建生产产物
`npm run preview`	预览生产产物

项目结构

text

src/
├── components/
├── views/
├── router/
├── stores/
└── main.ts

环境变量

复制 .env.example 为 .env.local 并填写必要配置。

部署

说明部署平台、构建命令和产物目录。

参考资料

Vite


### 10.2 学习文档模板

```markdown
# 技术名称系统学习文档

> 核对时间：2026-07-09  
> 适合人群：说明读者基础。  
> 学习目标：说明读完后能掌握什么。

---

## 目录

1. [是什么](#1-是什么)
2. [为什么要学](#2-为什么要学)
3. [核心概念](#3-核心概念)
4. [常用写法](#4-常用写法)
5. [项目实践](#5-项目实践)
6. [常见问题](#6-常见问题)
7. [官方资料](#7-官方资料)

---

## 1. 是什么

## 2. 为什么要学

## 3. 核心概念

## 4. 常用写法

## 5. 项目实践

## 6. 常见问题

## 7. 官方资料

10.3 技术方案模板

markdown

# 技术方案：方案名称

## 背景

说明为什么要做。

## 目标

- 目标一
- 目标二

## 非目标

- 本次不解决的问题

## 方案设计

说明架构、流程、数据结构、接口。

## 备选方案

| 方案 | 优点 | 缺点 | 是否采用 |
| --- | --- | --- | --- |
| A |  |  | 是 |
| B |  |  | 否 |

## 风险与应对

| 风险 | 影响 | 应对 |
| --- | --- | --- |
|  |  |  |

## 实施计划

1. 第一步
2. 第二步
3. 第三步

## 验收标准

- 标准一
- 标准二

10.4 ADR 模板

ADR 是 Architecture Decision Record，记录重要技术决策。

markdown

# ADR-001：使用 Vite 作为前端构建工具

## 状态

Accepted

## 日期

2026-07-09

## 背景

说明当前问题、约束和目标。

## 决策

采用 Vite 作为前端构建工具。

## 备选方案

### Webpack

- 优点：
- 缺点：
- 不采用原因：

### Rspack

- 优点：
- 缺点：
- 不采用原因：

## 后果

- 正面影响：
- 负面影响：
- 后续需要关注：

10.5 Changelog 模板

markdown

# Changelog

## [1.2.0] - 2026-07-09

### Added

- 新增功能。

### Changed

- 调整行为。

### Fixed

- 修复问题。

### Removed

- 移除废弃能力。

11. 写作规范与排版建议

11.1 一行写多长

中文技术文档可以不强制每行 80 字符，但建议：

一段不要太长。
每段只表达一个中心意思。
列表项尽量短。
表格不要横向过宽。

11.2 标题要具体

不推荐：

markdown

## 介绍

## 使用

## 其他

推荐：

markdown

## 1. Vite 是什么

## 2. 如何创建 Vite 项目

## 3. 常见问题与排查

11.3 先结论后细节

技术文档读者通常想快速定位信息。推荐结构：

text

结论
  -> 原因
  -> 示例
  -> 注意事项
  -> 参考资料

11.4 命令和路径用行内代码

推荐：

markdown

运行 `npm run dev` 启动项目，配置文件是 `vite.config.ts`。

不推荐：

markdown

运行 npm run dev 启动项目，配置文件是 vite.config.ts。

11.5 代码块必须可复制

不推荐：

bash

$ npm install
$ npm run dev

推荐：

bash

npm install
npm run dev

如果要展示输出，分开写：

bash

npm run build

输出：

text

dist/index.html
dist/assets/index.js

11.6 表格不要当万能布局工具

适合表格：

配置项说明。
命令说明。
对比信息。
风险清单。

不适合表格：

大段文字。
多层列表。
复杂代码。
需要频繁换行的内容。

11.7 链接文本要有意义

不推荐：

markdown

[点击这里](https://spec.commonmark.org/current/)

推荐：

markdown

[CommonMark 官方规范](https://spec.commonmark.org/current/)

11.8 统一术语

同一篇文档中不要混用：

Markdown / mark down / makedown
JavaScript / JS
TypeScript / TS

可以第一次写全称，后面使用简称：

markdown

TypeScript（以下简称 TS）是 JavaScript 的类型超集。

11.9 文档中的时间

推荐写核对时间：

markdown

> 核对时间：2026-07-09

技术生态变化快时尤其重要。

11.10 中英文混排与标点规范

中文技术文档的中英文混排，建议遵循「盘古之白」规则（中英文之间加空格）：

markdown

正确：使用 Vite 构建 Vue 项目。
错误：使用Vite构建Vue项目。

具体建议：

中文与英文单词、数字之间加一个半角空格。
中文与行内代码之间加空格：使用 npm install 安装。
中文句子内使用全角标点（，。！？；：），英文句子内使用半角标点。
数字和单位之间通常加空格：3 MB、100 ms（百分比 50% 例外，通常不加）。

示例：

markdown

不推荐：
该函数支持json和xml格式，返回boolean值。

推荐：
该函数支持 JSON 和 XML 格式，返回 boolean 值。

⚠️ 是否加空格是团队风格约定，不是硬性标准；关键是全篇统一。很多工具（如 pangu.js、各种 lint 插件）可以自动检查或补空格。代码块内的内容不要手动加空格（代码本身有语法约束）。

12. 常见错误与排查

12.1 标题没有空格

不推荐：

markdown

##标题

推荐：

markdown

## 标题

12.2 列表前后没有空行

不推荐：

markdown

下面是列表：
- A
- B
下一段。

推荐：

markdown

下面是列表：

- A
- B

下一段。

12.3 代码块没有关闭

错误：

markdown

```javascript
console.log("hello");

后面的所有内容都可能被当成代码。

正确：

markdown

```javascript
console.log("hello");
```

12.4 表格没有分隔行

错误：

markdown

| 命令 | 说明 |
| npm install | 安装依赖 |

正确：

markdown

| 命令 | 说明 |
| --- | --- |
| `npm install` | 安装依赖 |

12.5 链接括号写反

错误：

markdown

(GitHub)[https://github.com]

正确：

markdown

[GitHub](https://github.com)

12.6 图片路径在本地能看，GitHub 看不到

常见原因：

使用了本机绝对路径。
图片没有提交到仓库。
相对路径层级写错。
文件名大小写不一致。

排查：

确认图片文件存在。
确认路径相对当前 Markdown 文件。
确认文件名大小写完全一致。
在 GitHub/GitLab 页面实际预览。

12.7 表格里的竖线破坏布局

如果单元格中要显示 |，需要转义：

markdown

| 字符 | 写法 |
| --- | --- |
| 竖线 | `\|` |

12.8 不同平台渲染不一致

原因：

CommonMark 基础语法相对稳定。
GFM 是 GitHub 扩展。
Mermaid、数学公式、提示块、脚注属于平台或插件能力。

解决：

通用文档优先使用基础语法。
仓库文档可以使用 GFM。
文档站能力以对应工具文档为准。

13. 工具链建议

13.1 markdownlint

用于检查 Markdown 风格问题。

常见规则：

标题前后空行。
列表缩进。
代码块语言名。
重复标题。
行尾空格。

13.2 Prettier

Prettier 可以格式化 Markdown：

bash

npx prettier --write "**/*.md"

注意：格式化前先确认团队是否接受 Prettier 的换行和表格格式。

13.3 markdownlint-cli

bash

npm install markdownlint-cli -D
npx markdownlint "**/*.md"

13.4 文档站工具

工具	技术栈	适合场景
VitePress	Vue / Vite	前端团队文档、组件库文档
Docusaurus	React	开源项目文档站
MkDocs	Python	工程文档、内部知识库
Docsify	JS	轻量文档站

13.5 图表工具

Mermaid：流程图、时序图、类图。
PlantUML：复杂 UML 图。
Excalidraw：手绘风架构图。
draw.io：流程图、架构图。

Markdown 中可以放图片，也可以在支持的平台中直接写 Mermaid。

14. 学习检查题

Markdown 和 CommonMark 有什么关系？
GFM 在 CommonMark 基础上增加了哪些常用能力？
为什么 README 通常使用 .md 文件？
标题为什么建议 # 后面保留空格？
行内代码和代码块分别适合什么内容？
为什么代码块建议写语言名？
如何在 Markdown 文档里展示包含三个反引号的代码块？
表格中如何显示竖线 |？
图片 alt 文本有什么作用？
为什么仓库内部链接推荐使用相对路径？
为什么不建议大量 HTML 混写？
长文档为什么需要目录和稳定标题？

15. 官方资料

CommonMark 官方规范：https://spec.commonmark.org/current/
GitHub Flavored Markdown 规范：https://github.github.com/gfm/
GitHub Docs：基础写作和格式化语法：https://docs.github.com/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
GitHub Docs：表格写法：https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
GitHub Docs：高级格式化：https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting
markdownlint：https://github.com/DavidAnson/markdownlint
Prettier Markdown：https://prettier.io/docs/en/options.html

Markdown 文件写法学习文档 ​

目录 ​

1. Markdown 是什么 ​

项目说明 ​

2. Markdown、CommonMark 与 GFM 的关系 ​

2.1 Markdown ​

2.2 CommonMark ​

2.3 GitHub Flavored Markdown ​

2.4 实际写作建议 ​

3. 文件与编辑环境 ​

3.1 文件扩展名 ​

3.2 文件编码 ​

3.3 常用编辑器 ​

3.4 VS Code 常用能力 ​

3.5 Frontmatter（YAML 头） ​

4. 基础语法 ​

4.1 标题 ​

4.2 段落 ​

4.3 换行 ​

4.4 粗体、斜体、删除线 ​

4.5 无序列表 ​

4.6 有序列表 ​

4.7 嵌套列表 ​

4.8 引用 ​

4.9 分割线 ​

4.10 行内代码 ​

4.11 代码块 ​

4.12 链接 ​

4.13 图片 ​

4.14 转义字符 ​

4.15 内联 HTML ​

4.16 列表嵌套的精确缩进规则 ​

5. GitHub Flavored Markdown 扩展 ​

5.1 表格 ​

5.2 任务列表 ​

5.3 删除线 ​

5.4 自动链接 ​

5.5 脚注 ​

5.6 警告块和提示块 ​

5.7 Mermaid 图 ​

5.8 数学公式 ​

6. 图片、相对路径与资源管理 ​

6.1 推荐目录结构 ​

6.2 相对路径与绝对路径 ​

6.3 图片 alt 文本 ​

6.4 图片大小 ​

7. 代码块、嵌套代码块与语法高亮 ​

7.1 代码块语言名 ​

7.2 展示 Markdown 代码块 ​

7.3 列表中的代码块 ​

8. HTML、转义与兼容性 ​

8.1 Markdown 中能写 HTML 吗 ​

8.2 什么时候不建议写 HTML ​

8.3 HTML 与 Markdown 混写的坑 ​

8.4 特殊字符 ​

9. 目录、锚点与长文档结构 ​

9.1 手写目录 ​

9.2 GitHub 标题锚点规则 ​

9.3 长文档推荐结构 ​

9.4 GitHub 锚点生成算法（精确规则） ​

10. 常见文档模板 ​

10.1 README 模板 ​

常用命令 ​

项目结构 ​

环境变量 ​

部署 ​

参考资料 ​

10.3 技术方案模板 ​

10.4 ADR 模板 ​

10.5 Changelog 模板 ​

11. 写作规范与排版建议 ​

11.1 一行写多长 ​

11.2 标题要具体 ​

11.3 先结论后细节 ​

11.4 命令和路径用行内代码 ​

11.5 代码块必须可复制 ​

11.6 表格不要当万能布局工具 ​

11.7 链接文本要有意义 ​

11.8 统一术语 ​

11.9 文档中的时间 ​

Markdown 文件写法学习文档

目录

1. Markdown 是什么

项目说明

2. Markdown、CommonMark 与 GFM 的关系

2.1 Markdown

2.2 CommonMark

2.3 GitHub Flavored Markdown

2.4 实际写作建议

3. 文件与编辑环境

3.1 文件扩展名

3.2 文件编码

3.3 常用编辑器

3.4 VS Code 常用能力

3.5 Frontmatter（YAML 头）

4. 基础语法

4.1 标题

4.2 段落

4.3 换行

4.4 粗体、斜体、删除线

4.5 无序列表

4.6 有序列表

4.7 嵌套列表

4.8 引用

4.9 分割线

4.10 行内代码

4.11 代码块

4.12 链接

4.13 图片

4.14 转义字符

4.15 内联 HTML

4.16 列表嵌套的精确缩进规则

5. GitHub Flavored Markdown 扩展

5.1 表格

5.2 任务列表

5.3 删除线

5.4 自动链接

5.5 脚注

5.6 警告块和提示块

5.7 Mermaid 图

5.8 数学公式

6. 图片、相对路径与资源管理

6.1 推荐目录结构

6.2 相对路径与绝对路径

6.3 图片 alt 文本

6.4 图片大小

7. 代码块、嵌套代码块与语法高亮

7.1 代码块语言名

7.2 展示 Markdown 代码块

7.3 列表中的代码块

8. HTML、转义与兼容性

8.1 Markdown 中能写 HTML 吗

8.2 什么时候不建议写 HTML

8.3 HTML 与 Markdown 混写的坑

8.4 特殊字符

9. 目录、锚点与长文档结构

9.1 手写目录

9.2 GitHub 标题锚点规则

9.3 长文档推荐结构

9.4 GitHub 锚点生成算法（精确规则）

10. 常见文档模板

10.1 README 模板

常用命令

项目结构

环境变量

部署

参考资料

10.3 技术方案模板

10.4 ADR 模板

10.5 Changelog 模板

11. 写作规范与排版建议

11.1 一行写多长

11.2 标题要具体

11.3 先结论后细节

11.4 命令和路径用行内代码

11.5 代码块必须可复制

11.6 表格不要当万能布局工具

11.7 链接文本要有意义

11.8 统一术语

11.9 文档中的时间