MARKDOWN · 写作 / 标记语法
Markdown 语法速查
一张表看懂 Markdown 常用语法：元素、写法与渲染效果三列对照，从标题、列表到表格、任务列表，另附 README / 周报 / 接口文档三套骨架与高频渲染翻车点，写作排版随查随用。
33语法元素
5翻车点
3套骨架
📖 速查表
点击展开速查表
📚 Markdown 语法参考
| 元素 | 语法（Markdown） | 渲染效果 |
|---|---|---|
| 标题 | # H1 ~ ###### H6 | H1 ~ H6 |
| 加粗 | **加粗文字** | 加粗文字 |
| 斜体 | *斜体文字* | 斜体文字 |
| 链接 | [显示文字](https://url.com) | 显示文字 🔗 |
| 图片 |  | 显示图片 |
| 无序列表 | - 项目 1 - 项目 2 |
• 项目 1 • 项目 2 |
| 有序列表 | 1. 第一项 2. 第二项 |
1. 第一项 2. 第二项 |
| 代码 行内 | `code` | code |
| 代码块 | ```javascript console.log(1) ``` |
语法高亮的代码块 |
| 引用 | > 引用文字 | 引用文字 |
| 分割线 | --- | 水平分割线 |
| 表格 | | 表头 | 表头 | |------|------| | 内容 | 内容 | |
标准 Markdown 表格 |
| 任务列表 | - [x] 已完成 - [ ] 未完成 |
☑️ 已完成 ⬜ 未完成 |
| 删除线 | ~~删除文字~~ | |
| 脚注 | 文字[^1] [^1]: 注释 |
带脚注链接 |
🧩 GFM 扩展语法
GFM（GitHub Flavored Markdown）在标准语法之外的增补：基础表里已有的任务列表、删除线、脚注不重复列，这里只收 GitHub 特色能力。
| 元素 | 语法（Markdown） | 渲染效果 |
|---|---|---|
| 提及与引用 GFM | @username #123 | 自动链接到用户主页与 Issue，通知对方 |
| 警示块 GFM | > [!NOTE] > [!WARNING] |
五色提示框（NOTE/TIP/IMPORTANT/WARNING/CAUTION） |
| 数学公式 GFM | $E=mc^2$ $$…$$ |
行内与块级 LaTeX 渲染 |
| emoji 简码 | :smile: :rocket: | 😄 🚀 |
| 高亮 | ==重点文字== | 重点文字（Typora 等支持） |
| 自动链接 | <https://example.com> | https://example.com 🔗 |
📊 进阶排版
| 元素 | 语法（Markdown） | 渲染效果 |
|---|---|---|
| 嵌套列表 | - 父项 - 子项（子级缩进对齐父级内容：无序缩 2 空格、有序缩 3 空格） |
• 父项 ◦ 子项 |
| 表格对齐 | | :--- | :---: | ---: | 单元格内竖线用 \| 转义 |
左对齐 / 居中 / 右对齐 |
| 多级引用 | > 一级引用 >> 二级引用 |
一级引用套二级引用 |
| 折叠块 | <details> <summary>标题</summary> 内容 </details> |
▶ 点击展开的折叠区域 |
| 图片指定宽高 | <img src="url" width="200"> | 控制尺寸的图片（原生语法不支持宽高时用 HTML） |
| 代码块语言 | ```java / ```js / ```sql ```bash / ```json / ```yaml |
对应语言的语法高亮 |
🛠️ 工具与场景
| 元素 | 语法（Markdown） | 渲染效果 |
|---|---|---|
| Typora | 所见即所得编辑器，打字即渲染，Ctrl+/ 切换源码模式 | 沉浸式写作首选 |
| Obsidian | 本地 Markdown 库 + 双链 + 关系图谱 | 个人知识管理库 |
| VS Code | Ctrl+Shift+V 打开预览，写作 + 预览两不误 | 边写边看的轻量方案 |
| Mermaid 图表 | ```mermaid graph TD; A-->B; ``` |
用代码画流程图 / 时序图 |
| README 场景 | 项目简介 → 徽章 → 安装 → 快速上手 → 示例 → License | 让别人 3 分钟用起来 |
| 周报 / 接口文档 | 周报：进展 / 风险 / 计划三段式；接口文档：参数表格 + 请求响应示例 | 结构化，减少来回沟通 |
📝 三合一文档骨架
最常写的三类文档各留一套可复制改写的骨架：README 让人 3 分钟跑起来，周报让领导 30 秒抓住重点，接口文档让前后端零口头沟通。整段复制到编辑器，删注释换内容即可。
<!-- ① README 骨架：标题 → 徽标 → 一句话简介 → 安装 → 用法 → 目录 -->
# project-name
 
一句话说清：解决什么问题、给谁用、凭什么选它。
## 安装
```bash
git clone https://github.com/you/project.git
cd project && npm install
```
## 用法
```js
import { createApp } from './src/app.js'
createApp({ port: 3000 }).start() // 最小可运行示例
```
## 目录
- [快速上手](#安装) · [常见问题](#faq) · [Contributing](#contributing)
<!-- ② 周报骨架：结果 → 风险 → 计划，每段不超过 5 行 -->
## 本周结果
- 搜索链路重构上线，P99 延迟 480ms → 210ms
## 风险与求助
- 订单服务联调阻塞中，需 @平台组 周三前给出接口
## 下周计划
- [ ] 灰度 10% 流量观察一周
- [ ] 补齐压测报告
<!-- ③ 接口文档骨架：路径 → 用途 → 参数表 → 示例 -->
## POST /api/v1/orders
创建订单，幂等键防止重复下单。
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| skuId | long | 是 | 商品 ID |
| count | int | 是 | 购买数量 1~99 |
| idempotentKey | string | 是 | 幂等键，客户端生成 UUID |
```json
{ "code": 0, "data": { "orderId": 10086 } }
```
🧯 渲染翻车点
Markdown 本身不难，难的是各渲染器对细节的苛求：这 5 个高频翻车点覆盖了九成的「我本地明明是好的」，对照症状找解法。
| 翻车现场 | 原因 | 解法 |
|---|---|---|
| 列表写出来还是普通文字，- 原样显示 最高频 | 列表与上一段正文之间缺少空行，紧贴段落不解析 | 列表前空一行，- 后记得跟空格 |
| 嵌套子列表层级错乱，甚至整段被当成代码块 缩进敏感 | 缩进数不对：无序子列表缩 2 空格、有序缩 3 空格，须与父项文字对齐；Tab 与空格混用必翻车 | 编辑器设置 Tab 转空格，粘贴后统一重排缩进 |
| 单元格里的 a|b 把表格多切出一列 分隔符冲突 | 竖线是列分隔符，字面竖线会被当成新列 | 写成 a\|b 转义，行内代码里也一样 |
| 代码块一片灰黑，没有语法高亮 标签缺失 | 围栏 ``` 后没写语言标签，渲染器不知按什么高亮 | 标注 ```java / ```bash；js / sh / yml 等别名也认 |
| 本地好好的 HTML 混写，推到平台后消失或原样显示 平台差异 | 各平台对 HTML 有白名单过滤（如 GitHub 只放行部分标签），策略互不相同 | 优先纯 Markdown 语法；确需 HTML 只用平台验证过的标签，发布前预览确认 |