Markdown写作技巧与排版艺术：从基础到专业
这些年我几乎所有东西都用 Markdown 写——README、内部文档、博客草稿、甚至开会的临时记录。一开始觉得它就是"加几个井号"那么简单，直到有一天我写好的一张对照表，在 GitHub 上排得整整齐齐，复制到 Typora 里却莫名其妙错了一列，丢到 VS Code 预览又是另一个样子。最折磨我的是嵌套列表：明明缩进看起来对齐了，渲染出来子项却全挤回了一级，我盯着那两个空格和四个空格的差别看了快十分钟。
所以这篇不是语法手册的搬运，而是我踩了几年坑攒下来的经验：哪些语法真的会用到，哪些渲染器之间会打架，以及怎么写才不至于换个平台就崩。
先把我那次"同一份文档在四个地方四个样"的教训摆出来。下面这张表是我后来专门测出来的，主流渲染器在几个最容易出事的语法上各有各的脾气：
| 语法 | GitHub | Typora | VS Code 预览 | 微信公众号 | 踩坑点 |
|---|---|---|---|---|---|
| 表格 | 原生支持 | 支持，但对齐写法更挑 | 支持 | 多数编辑器转成图片或样式块 | 列数对不上时各家容错不同，少写一个竖线就可能错列 |
| 单换行（行内换行） | 不换行，需行末两空格或 <br> | 直接按回车就换行 | 不换行 | 视编辑器而定 | Typora 里看着好好的换行，发到 GitHub 全挤成一段 |
| 嵌套列表缩进 | 2 空格即可生效 | 2 空格生效 | 偏向 4 空格 | 经常缩进丢失 | 2 空格还是 4 空格不统一，子项会被"打回"上一级 |
| HTML 支持 | 支持大部分标签 | 支持 | 支持 | 几乎全部过滤 | 依赖 <div>/<img width> 的排版，到公众号直接失效 |
| 数学公式 | 支持 $...$ / $$...$$ | 支持 LaTeX | 需装插件 | 不支持 | 公式在本地好好的，换平台可能整行变成纯文本 |
记住一句话就够了：缩进、换行、HTML 这三样是跨平台的重灾区，写之前先想好最终发到哪儿。
目录
Markdown基础语法
标题
Markdown使用#表示标题，1-6个#对应H1-H6：
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
排版建议：
- 文档只用一个H1标题（通常是文章标题）
- H2用于主要章节，H3用于子章节
- 不要跳级使用（如H2直接跳到H4）
- 标题前后各空一行，提高可读性
段落和换行
这是第一段文字。
这是第二段文字。
如果要在段落内换行，
在行末添加两个空格。
常见错误：
❌ 段落之间只有一个换行符
这是第一段
这是第二段
✅ 段落之间空一行
这是第一段
这是第二段
强调
_斜体_ 或 _斜体_
**粗体** 或 **粗体**
**_粗斜体_** 或 **_粗斜体_**
~~删除线~~
效果：
- 斜体文字
- 粗体文字
- 粗斜体
删除的文字
列表
无序列表：
- 项目1
- 项目2
- 子项目2.1
- 子项目2.2
- 项目3
或使用 \* 或 +：
- 项目A
* 项目B
有序列表：
1. 第一项
2. 第二项
1. 子项2.1
2. 子项2.2
3. 第三项
技巧：可以全部使用1.，渲染时会自动编号：
1. 第一项
1. 第二项
1. 第三项
任务列表（GitHub、GitLab支持）：
- [x] 已完成任务
- [ ] 待办任务
- [ ] 另一个待办
链接
[链接文字](https://example.com)
[带标题的链接](https://example.com '鼠标悬停显示')
<!-- 参考式链接 -->
这是[参考链接][1]的示例。
[1]: https://example.com
自动链接：
<https://example.com>
<email@example.com>
图片
<!-- 参考式图片 -->
![Logo][logo]
[logo]: https://example.com/logo.png
图片尺寸（HTML语法）：
<img src="image.png" width="300" alt="描述">
引用
> 这是一段引用文字。
>
> 引用可以包含多个段落。
> 引用可以嵌套
>
> > 二级引用
> >
> > > 三级引用
效果：
这是一段引用文字。
可以用于引用他人的话，或重要提示。
代码
行内代码：
使用 `console.log()` 打印日志。
代码块：
```javascript
function hello() {
console.log('Hello, World!');
}
```
语法高亮：
```python
def factorial(n):
return 1 if n <= 1 else n * factorial(n - 1)
```
支持的语言标识：
javascript/jstypescript/tspython/pyjavacpp/c++csshtmlbash/shellsqljsonmarkdown/md
表格
| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 内容1 | 内容2 | 内容3 |
| 长内容 | 短 | 中等 |
效果：
| 左对齐 | 居中对齐 | 右对齐 |
|---|---|---|
| 内容1 | 内容2 | 内容3 |
| 长内容 | 短 | 中等 |
对齐方式：
:---左对齐（默认）:---:居中对齐---:右对齐
分隔线
---
---
---
高级排版技巧
脚注
这是一段包含脚注的文字[^1]。
[^1]: 这是脚注内容。
目录生成
很多Markdown编辑器支持自动生成目录：
[TOC]
或者手动创建：
## 目录
- [章节1](#章节1)
- [章节2](#章节2)
- [子章节2.1](#子章节21)
数学公式（LaTeX）
行内公式：$E = mc^2$
块级公式：
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$
流程图（Mermaid）
```mermaid
graph TD
A[开始] --> B{判断}
B -->|是| C[执行操作]
B -->|否| D[结束]
C --> D
```
时序图
```mermaid
sequenceDiagram
用户->>服务器: 发送请求
服务器->>数据库: 查询数据
数据库-->>服务器: 返回结果
服务器-->>用户: 响应数据
```
HTML嵌入
Markdown支持嵌入HTML：
<div style="color: red; font-weight: bold;">
这是红色粗体文字
</div>
<details>
<summary>点击展开</summary>
隐藏的内容
</details>
转义字符
如果要显示Markdown特殊字符，使用反斜杠转义：
\* 这不是列表
\# 这不是标题
\[这不是链接\]
不同平台的Markdown差异
GitHub Flavored Markdown (GFM)
GitHub扩展了标准Markdown：
1. 任务列表：
- [x] 支持任务列表
- [ ] 这是GFM特性
2. 表格：
支持更灵活的表格语法。
3. 自动链接：
访问 www.github.com
或发邮件到 user@example.com
4. 删除线：
~~删除的文字~~
5. Emoji：
:smile: :heart: :thumbsup:
6. @提及和#引用：
@username
#123 (引用issue)
微信公众号Markdown
微信公众号的Markdown编辑器（如墨滴、Markdown Nice）有特殊要求：
样式限制：
- 不支持HTML标签
- 不支持某些CSS样式
- 图片必须上传到图床
推荐工具：
- Markdown Nice：在线编辑器，一键复制到公众号
- 墨滴：专为公众号设计的编辑器
排版技巧：
<!-- 使用引用突出重点 -->
> 📌 重要提示：这里是关键内容
<!-- 使用表格优化布局 -->
| 功能 | 描述 |
| ----- | ---- |
| 功能A | 说明 |
<!-- 使用代码块展示代码 -->
```javascript
// 代码示例
```
### Notion
Notion的Markdown支持：
**导入**：
- 支持`.md`文件导入
- 自动转换为Notion blocks
**导出**：
- 可导出为Markdown格式
- 保留大部分格式
**特殊语法**：
```markdown
/code - 创建代码块
/table - 创建表格
/image - 插入图片
Jupyter Notebook
Jupyter支持Markdown cells：
LaTeX支持：
$$ \int\_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$
特殊功能：
- 支持HTML
- 支持LaTeX
- 可嵌入图片和视频
实战案例
案例1：技术博客文章
---
title: 'React Hooks深度解析'
date: 2024-01-01
tags: [React, JavaScript, Hooks]
---
# React Hooks深度解析
## 引言
React Hooks改变了我们编写组件的方式...
## useState详解
`useState`是最基础的Hook：
```javascript
import { useState } from 'react';
function Counter() {
const [count, setCount] = useState(0);
return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}
```
工作原理
useState背后的实现...
useEffect详解
...
总结
- ✅ Hooks让组件更简洁
- ✅ 避免生命周期的复杂性
- ✅ 更容易复用逻辑
参考资料：
### 案例2：API文档
```markdown
# User API
## 获取用户信息
**端点**：`GET /api/users/:id`
**参数**：
| 参数名 | 类型 | 必需 | 描述 |
|--------|--------|------|----------|
| id | string | 是 | 用户ID |
**响应**：
```json
{
"id": "123",
"name": "张三",
"email": "zhang@example.com",
"created_at": "2024-01-01T00:00:00Z"
}
错误码：
| 错误码 | 描述 |
|---|---|
| 404 | 用户不存在 |
| 500 | 服务器错误 |
示例：
curl -X GET https://api.example.com/users/123 \
-H "Authorization: Bearer TOKEN"
### 案例3：GitHub README
```markdown
# 项目名称
[]()
[]()
> 一句话描述项目
## 特性
- ✨ 特性1
- 🚀 特性2
- 💪 特性3
## 快速开始
### 安装
```bash
npm install package-name
使用
import { feature } from 'package-name';
feature.doSomething();
API文档
详见 API.md
贡献
欢迎贡献！请阅读 CONTRIBUTING.md
许可证
联系方式
- 作者：张三
- 邮箱：zhang@example.com
- 主页：https://example.com
### 案例4：学习笔记
```markdown
# JavaScript异步编程学习笔记
## 日期：2024-01-01
### 今日学习
#### 1. Promise基础
Promise有三种状态：
- **Pending**（进行中）
- **Fulfilled**（已成功）
- **Rejected**（已失败）
```javascript
const promise = new Promise((resolve, reject) => {
setTimeout(() => {
resolve('成功');
}, 1000);
});
promise.then(result => {
console.log(result); // '成功'
});
2. async/await
async/await是Promise的语法糖：
async function fetchData() {
try {
const response = await fetch('/api/data');
const data = await response.json();
return data;
} catch (error) {
console.error('Error:', error);
}
}
重点总结
💡 关键点：
- Promise链可以避免回调地狱
- async/await让异步代码看起来像同步
- 记得处理错误（try-catch或.catch）
练习题
- 实现一个延迟函数
- 并发请求3个API
- 实现Promise.all
参考资料
## 最佳实践
### 1. 文件结构
```markdown
# 文档标题（H1，全文只有一个）
简短的引言段落，介绍文档内容。
## 目录
自动生成或手动列出主要章节。
## 章节1（H2）
内容...
### 子章节1.1（H3）
内容...
## 章节2
内容...
## 总结
总结要点。
## 参考资料
列出参考链接。
2. 代码块最佳实践
<!-- ✅ 好的代码块 -->
```javascript
// 清晰的注释
function add(a, b) {
return a + b;
}
// 使用示例
const result = add(2, 3); // 5
```
add(2,3)
### 3. 链接管理
**参考式链接**（适合多次引用同一链接）：
```markdown
文中多次提到[React][react]和[Vue][vue]。
React是[Facebook][facebook]开发的。
[react]: https://react.dev
[vue]: https://vuejs.org
[facebook]: https://facebook.com
4. 图片优化
<!-- 使用相对路径 -->
<!-- 添加有意义的alt文本 -->
<!-- 控制图片大小 -->
<img src="large-image.png" width="600" alt="描述">
5. 表格排版
<!-- ✅ 对齐良好，易读 -->
| 姓名 | 年龄 | 城市 |
| ---- | ---- | ---- |
| 张三 | 25 | 北京 |
| 李四 | 30 | 上海 |
<!-- ❌ 虽然有效，但难以维护 -->
| 姓名 | 年龄 | 城市 |
| ---- | ---- | ---- |
| 张三 | 25 | 北京 |
6. 层级结构
<!-- ✅ 清晰的层级 -->
# 主标题
## 章节1
### 子章节1.1
#### 小节1.1.1
<!-- ❌ 避免跳级 -->
# 主标题
### 直接跳到H3（跳过H2）
7. 中英文混排
<!-- ✅ 中英文之间加空格 -->
使用 JavaScript 编写前端代码。
<!-- ❌ 不加空格难以阅读 -->
使用JavaScript编写前端代码。
<!-- 数字与中文之间也加空格 -->
我有 3 个苹果。
8. 引用格式
<!-- ✅ 用于引用 -->
> 你好，引用！
> — 作者名，《书名》
<!-- ✅ 用于提示 -->
> ⚠️ **警告**：这是重要提示。
> 💡 **提示**：这是小技巧。
> ✅ **成功**：操作完成。
工具推荐
编辑器
-
VS Code + Markdown插件
- Markdown All in One
- Markdown Preview Enhanced
- markdownlint（语法检查）
-
Typora
- 所见即所得
- 实时预览
- 支持导出PDF
-
在线编辑器
格式检查
markdownlint 规则：
<!-- MD001: 标题层级递增 -->
# H1
## H2
### H3
<!-- MD004: 无序列表统一符号 -->
- 项目1
- 项目2
<!-- MD009: 行末无空格 -->
正确的行末
<!-- MD012: 不要有连续空行 -->
<!-- MD022: 标题前后要有空行 -->
## 标题
内容
<!-- MD026: 标题末尾不加标点 -->
## 这是标题
转换工具
- Pandoc：Markdown ↔️ Word/PDF/HTML
- marked：JavaScript Markdown解析器
- markdown-it：可扩展的Markdown解析器
写在最后
写了这么多语法，但说句实在话：别迷信那些花哨的特性。我自己 90% 的内容就靠标题、列表、代码块、表格这四样撑起来，脚注、Mermaid、复杂 HTML 这些一年也用不上几次，真要排版精致的东西，我宁愿换个专门工具，也不在 Markdown 里硬塞一堆标签——到头来换个平台全崩，得不偿失。
最值得记住的还是开头那张表里的教训：换行、缩进、HTML 这些行为，各家渲染器真的不一样。我现在的习惯是，重要的文档发布前一定在目标平台（GitHub 也好、公众号也好）先预览一遍，别等读者看到错位的表格才发现。这点小动作，帮我省了无数次返工。
如果你想随手验证一段 Markdown 长什么样，我们这个 Markdown 编辑器 是纯浏览器里跑的，内容不上传、打开即用，边写边看效果，挺适合发布前对照检查。好了，去写点东西吧，比看一百篇教程都管用。
相关工具
- 📝 Markdown编辑器 - 在线编辑和预览
- 🔄 HTML转Markdown - 格式转换
- ✅ Markdown语法检查 - 检查格式
关键词: Markdown, 技术写作, 排版, GitHub, 文档
更新时间: 2026-01-05
我们是一支开发者小团队，负责构建和维护 ToolsForge —— 150+ 个完全在浏览器本地运行、隐私优先的工具。这些文章来自我们日常的工程实践，而不是纸上谈兵。
了解我们相关阅读
一张照片能做多少事：AI 改图工具实战指南
换发型、换发色、换装、转卡通、风格迁移、室内设计、老照片修复——用一张照片走完这些 AI 改图流程,以及怎么让结果更稳、更像本人。
把脸保住：AI 改图提示词怎么写才不"换人"
换发型、换装、换风格时,AI 老把脸也改了?这篇讲清楚改图提示词的写法:保人约束、双通道(gpt-image-2 / Nano Banana)各自的脾气,以及一套能直接抄的模板。
TypeScript 类型体操：什么时候值，什么时候在炫技
务实的 TypeScript 高级类型指南 — mapped types、conditional types、template literal types 真正能给你什么，什么时候用，什么时候应该退回到朴素代码。