Markdown 转 HTML 完全指南：从语法基础到高级排版技巧

文档效率（更新于 2026年6月2日）

为什么用 Markdown？

Markdown 是技术文档的事实标准——GitHub、Stack Overflow、Notion、VS Code 都原生支持。

对比 Markdown Word HTML
学习成本 低 中 高
版本控制 ✅ 纯文本 ❌ 二进制 ✅ 纯文本
可读性 ✅ 源码即文档 ❌ ❌
表达力 中（扩展后强） 强 强
渲染一致性 中 ❌ 各平台不同 ✅

基础语法速查

标题

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

强调

**粗体**    → <strong>粗体</strong>
*斜体*      → <em>斜体</em>
~~删除线~~  → <del>删除线</del>
`行内代码`  → <code>行内代码</code>

列表

- 无序列表项 1
- 无序列表项 2
  - 嵌套项

1. 有序列表项 1
2. 有序列表项 2
   1. 嵌套有序

- [ ] 待办事项（未完成）
- [x] 待办事项（已完成）

链接与图片

[链接文字](https://example.com)
[带标题的链接](https://example.com "标题")
![图片替代文字](image.png)
![带标题的图片](image.png "图片标题")

引用与分割线

> 引用文字
> > 嵌套引用

---

GFM 扩展语法

表格

| 左对齐 | 居中 | 右对齐 |
|:-------|:----:|-------:|
| 内容   | 内容 | 内容   |
| 长内容 | 短   | 中等   |

渲染结果：

左对齐 居中 右对齐
内容 内容 内容
长内容 短 中等

任务列表

- [x] 需求分析
- [x] 技术设计
- [ ] 开发实现
- [ ] 测试验收

围栏代码块

```javascript
function hello() {
  console.log('Hello, Markdown!');
}
```

```python
def hello():
    print("Hello, Markdown!")
```

脚注

这是一段文字[^1]，还有另一段[^note]。

[^1]: 这是第一个脚注的内容。
[^note]: 这是自定义 ID 的脚注。

高级排版技巧

1. 数学公式（KaTeX/MathJax）

行内公式：$E = mc^2$

块级公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

矩阵：
$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
$$

2. Mermaid 图表

```mermaid
graph TD
    A[用户请求] --> B{认证检查}
    B -->|已认证| C[获取数据]
    B -->|未认证| D[返回 401]
    C --> E[渲染页面]
```

支持的图表类型：

类型 语法关键字 用途
流程图 graph 业务流程、决策树
时序图 sequenceDiagram API 调用、交互流程
类图 classDiagram 面向对象设计
状态图 stateDiagram 状态机
甘特图 gantt 项目排期
饼图 pie 数据占比

3. 目录（TOC）

<!-- 自动生成目录 -->
[[toc]]

<!-- 或手动 -->
- [安装](#安装)
- [配置](#配置)
- [使用](#使用)

4. 定义列表

术语 1
: 定义 1

术语 2
: 定义 2

5. 缩写

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

HTML 是 W3C 制定的标准。

使用工具库转换 Markdown

操作步骤

  1. 打开 Markdown 编辑器
  2. 在左侧编辑区输入 Markdown
  3. 右侧实时预览 HTML 渲染结果
  4. 可切换"源码"模式查看生成的 HTML
  5. 支持导出为 HTML 文件

支持的扩展

扩展 说明 示例
GFM 表格、任务列表、脚注 GitHub 风格
数学公式 KaTeX 渲染 $E=mc^2$
Mermaid 图表渲染 流程图、时序图
语法高亮 Prism.js/highlight.js 代码块着色
Emoji :smile: → 😄 短代码替换

Markdown 转 HTML 的原理

解析流程

Markdown 文本
  ↓
词法分析（Lexer）→ Token 流
  ↓
语法分析（Parser）→ AST（抽象语法树）
  ↓
渲染器（Renderer）→ HTML 字符串

主流解析库

库 语言 特点 大小
marked JS 最快、最流行 40KB
markdown-it JS 插件丰富、可扩展 60KB
remark JS AST 生态、MDX 基础 100KB+
CommonMark JS 严格标准合规 50KB
pulldown-cmark Rust 极致性能 WASM 200KB

marked 基础用法

import { marked } from 'marked';

const html = marked.parse('# Hello **Markdown**');
// <h1>Hello <strong>Markdown</strong></h1>

markdown-it + 插件

import MarkdownIt from 'markdown-it';
import mk from 'markdown-it-mark';
import footnote from 'markdown-it-footnote';
import tasklist from 'markdown-it-task-lists';

const md = new MarkdownIt({ html: true, linkify: true })
  .use(mk)
  .use(footnote)
  .use(tasklist);

const result = md.render('# Hello Markdown');

MDX：Markdown + JSX

MDX 让你在 Markdown 中使用 React 组件：

---
title: "我的文章"
---

import { Chart } from './components/Chart';
import { Callout } from './components/Callout';

# 数据分析报告

<Callout type="warning">
  以下数据基于 2026 年 Q1 采样。
</Callout>

## 用户增长趋势

<Chart data={growthData} type="line" />

| 月份 | 用户数 | 增长率 |
|------|--------|--------|
| 1月  | 10,000 | -      |
| 2月  | 12,500 | 25%    |
| 3月  | 15,000 | 20%    |

最佳实践

1. 文件组织

docs/
├── getting-started.md
├── configuration.md
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

2. 写作规范

  • 一行一句：Git diff 友好，方便审查修改
  • 标题层级不跳级：H1 → H2 → H3，不要 H1 → H3
  • 代码块指定语言：````javascript` 而非 `````
  • 链接用引用式：长文档中 [文字][ref] 比 [文字](url) 更整洁
  • 图片加替代文字：![描述](图片) 提升可访问性

3. Lint 工具

# 安装 markdownlint
npm install -g markdownlint-cli

# 检查
markdownlint docs/**/*.md

# 自动修复
markdownlint docs/**/*.md --fix

常见问题

Markdown 中的 HTML 不生效？

部分解析器默认禁用原始 HTML，需要开启 html: true 选项。

表格不支持合并单元格？

标准 Markdown 表格不支持合并单元格。需要时使用 HTML 表格：

<table>
  <tr>
    <th>名称</th>
    <th>描述</th>
  </tr>
  <tr>
    <td rowspan="2">项目 A</td>
    <td>子项 1</td>
  </tr>
  <tr>
    <td>子项 2</td>
  </tr>
</table>

代码块中的 Markdown 语法被解析？

使用更多反引号嵌套：

````markdown
```javascript
console.log('不会被外层解析');
```


---

## 总结

Markdown 是技术写作的最佳格式——简洁、可版本控制、生态丰富。掌握基础语法 + GFM 扩展 + 数学公式 + Mermaid 图表，就能写出专业级技术文档。工具库的 [Markdown 编辑器](/zh-CN/docs/markdown) 提供实时预览和导出，让你专注内容而非排版。
#Markdown#HTML转换#文档编写#排版#教程