在线 Markdown 预览器：实时渲染和编辑 Markdown 文档

什么是 Markdown

Markdown 是一种轻量级标记语言，由 John Gruber 于 2004 年提出。它用可读的纯文本表达标题、列表、链接等结构，再由解析器转成 HTML 或其他格式。技术文档、README、博客与笔记里，它几乎是默认写法。

需要把同一份内容在 HTML 与 Markdown 之间搬运时，用 HTML ↔ Markdown 互转；需要边写边看最终排版时，用 Markdown 预览。

为什么需要预览

源码里「看起来对齐」不等于渲染后对齐。预览主要拦三类问题：

1. 结构类：表格分隔行少一列、代码围栏少三个反引号、嵌套列表缩进差一格
2. 方言类：在只吃 CommonMark 的系统里写了 GFM 表格，结果变成竖线原文
3. 发布前抽查：任务列表、引用、链接在目标站点上是否还能成立

散文段落通常不必每句都预览；表格、嵌套列表、围栏代码块才是高收益场景。

如何使用 ToolVault Markdown 预览

打开 Markdown 预览：

1. 默认进入分屏：左侧源码（Monaco / CodeEditor），右侧即时渲染
2. 可切换 源码（只看编辑器）或 预览（只看渲染），视图偏好会写入本地键 tool:markdown:view
3. 首次打开带一份 GFM 示例（标题、任务列表、表格、引用、围栏代码），可直接改写验证
4. 可用工具栏 复制 HTML 拿到 marked 渲染的 HTML 字符串（与预览 DOM 同源方言 GFM；安全说明见下文 XSS 节）。也可继续用互转工具做双向编辑

渲染在浏览器本地完成，正文不会为了预览而 POST 到服务器。

CommonMark vs GFM：预览保真的第一问

Markdown 从诞生起就存在方言：

写 GFM 表格却在纯 CommonMark 渲染器里发布，经典症状是竖线原样显示。反过来：在只支持 GFM 的预览里写好的文档，搬到不认任务列表的旧 Wiki，复选框会退化成普通列表文本。

MediaWiki、部分旧 CMS、聊天软件子集，请在目标环境再预览一次——本站对齐的是开发者文档常见的 GFM，不是所有方言的并集。

基本语法与 GFM 扩展（以本工具为准）

标题、强调、列表、链接

# 一级标题
## 二级标题

**粗体** 与 *斜体*；行内代码用反引号。

- 无序一项
1. 有序一项

[链接文字](https://example.com)
![替代文本](https://example.com/image.png)

> 引用可以跨多行

删除线 ~~text~~ 属于 GFM，不是严格 CommonMark 核心。

围栏代码块

语言标签写在开头围栏后（例如标签 js）。本工具会把内容放进等宽 pre / code，并带上常见的 language-* class——但没有接入代码高亮插件，因此不会出现彩色关键字高亮。高亮需要 rehype-highlight / Prism 一类插件，或在目标文档站完成。

表格（GFM）

| 环境 | 域名 | 流量 |
|---|---|---:|
| 生产 | www.example.com | 100% |
| 预发 | staging.example.com | 内部 |

要点：

• 表头下一行的 |---| 列数必须与表头一致，否则常塌成纯文本
• 对齐靠分隔行里的冒号：:--- 左、---: 右、:---: 中
• 单元格内的 | 需写成 \|
• 空格对齐只方便人读源码，渲染器不依赖对齐空格

可视化拼表可用 Markdown 表格生成器；拼好后贴回本页确认。

任务列表（GFM）

- [x] 已完成
- [ ] 未完成

预览里会渲染为禁用状态的复选框（展示用）。交互勾选、把状态写回源码——本页不做；需要可勾选清单时用议题系统或专用应用。

自动链接

裸 URL（如 https://example.com）在 GFM 下常会变成可点链接。邮件字面量行为随解析器略有差异；以预览结果为准。

不在本工具能力内的「常见扩展」

安全渲染与 XSS 边界

本工具链路是：

源码字符串 → remark 解析（+ remark-gfm）→ react-markdown 生成 React 元素 → Tailwind Typography（prose）样式

关键边界（对照当前依赖行为，其他站点可能不同）：

1. 默认不把 Markdown 里的裸 HTML 当成真实 DOM 执行
   react-markdown 对 HTML 倾向转义或跳过，而不是 dangerouslySetInnerHTML 整段灌入。旧文若写「预览会原样跑脚本标签」——不符合本工具。FAQ 里「可以混用 HTML」指的是许多平台的方言能力，不是本页保证透传。

2. 链接与图片 URL 会走默认 urlTransform
   常见危险协议（如 javascript:）会被挡掉。不要自行关掉或改成「原样放行」——那是 XSS 开口。

3. 没有单独挂 rehype-sanitize 白名单插件
   安全主要来自「Markdown → React 元素」模型 + URL 变换，而不是 HTML 消毒器二次过滤。若你把互转工具吐出的 HTML 粘进自己的页面并用 innerHTML 挂载，那是另一条威胁模型——请用站点自己的消毒策略，或先看 HTML 实体编码指南。

4. 图片与外链仍可能触发隐私/混合内容问题
   ![x](https://…) 会发起浏览器请求；预览不含内容的站点不等于「图片 URL 零副作用」。内网地址、跟踪参数、超大图都要自己把关。

5. 对比：互转工具的 Markdown → HTML
   HTML ↔ Markdown 用 marked.parse 产出 HTML 字符串放进编辑器（文本），不是本页的 React 渲染路径。字符串里可以含 GFM 表格等标签；是否安全取决于你之后如何嵌入页面。

预览 ≠ 发布：两件不同的事

本地预览回答的是「这份 GFM 文档是不是按我想象解析」。发布还要过更长清单：frontmatter 元数据、图片 CDN 路径、相对/绝对链接、MDX/JSX 规则（正文里裸的小于号可能打断 MDX）、站点短代码。把本工具当成语法与排版冒烟，不要当成目标站构建的替代品。

一个省评审往返的实用循环：

1. 先在本页把结构写顺（标题、表格、任务列表），分屏看着对再走下一步
2. 围栏里的配置先过 YAML ↔ JSON 或 JSON 格式化，保证示例本身合法
3. 再到目标环境预览一次（GitHub PR、文档站、CMS），核对本页不宣称的扩展

若第 3 步失败而第 1 步看起来正常，问题几乎总在扩展或消毒策略，而不是标题/粗体。把失败构造缩成两行复现（一行表格、一层嵌套列表），避免评审对照整份 README。目标站若启用数学、告示块、mermaid 等插件，在 PR 里写明——别把本页浏览器预览当成最终渲染器。

「复制 HTML」与屏幕预览不是同一条路径

工具栏 复制 HTML 走 marked（GFM），把 HTML 字符串放进剪贴板；右侧窗格仍是 react-markdown + remark-gfm。两者都以 GFM 表格与任务列表为目标，但代码路径不同：

复制 HTML 适合邮件模板、静态片段、或要求 markup 的 CMS 字段。不要把剪贴板字符串当成「已经为生产消过毒」。

常见踩坑

代码围栏少闭合

少一组 ``` 会让后半篇全部变成代码样式——预览里「从某行起全是等宽」就是信号。

嵌套列表缩进

二级列表通常需要与父项文字对齐（常见 2 或 4 空格）。Tab 与空格混用时，不同渲染器表现不一致；本站跟 CommonMark/GFM 规则走，以预览为准。

硬换行 vs 段落

默认（breaks: false 一类语义）单个换行往往并进同一段落；要硬换行用行尾两个空格或空行分段。GitHub 评论区与部分聊天客户端更激进，不要假设「源码里换行 = 预览换行」。

脚注与引用式链接

GFM 脚注（[^1]）在目标站支持时才会完整可用；本预览跟 remark-gfm 脚注规则。引用式链接（[文字][id] + 文末定义）若定义行缩进进了列表或围栏，很容易断链——定义行保持顶格。

预览与生产不一致时怎么查

1. 缩成两行可复现用例
2. 确认两侧是否都是 GFM（尤其表格/任务列表/删除线）
3. 查目标站是否剥 HTML、改自动链接、换数学插件
   元凶几乎总在扩展边界，而不是 # / ** 这类核心语法。

和 YAML、JSON、Diff、HTML 一起用

注意：Markdown 预览不是 Diff 工具，也不会解析 YAML frontmatter 语义。

实现注记

以下描述对应本站 MarkdownTool（src/components/DataTool.tsx）的真实行为：

• 解析栈：react-markdown + 唯一 remark 插件 remark-gfm。未配置 rehype-highlight、remark-math、remark-emoji、rehype-raw、rehype-sanitize。
• 样式：预览容器使用 Tailwind Typography 的 prose prose-sm（含 dark 变体），不是另一套 Markdown CSS 框架。
• 视图：split / source / preview 三态；默认分屏；偏好经 usePersistentState 持久化。
• 复制 HTML：工具栏按钮用 marked（GFM）生成 HTML 字符串；屏幕预览仍走 react-markdown。嵌入自有页面前请自行消毒。
• 无彩色语法高亮：围栏语言标签可能体现在 class 上，但页面不着色。
• emoji 短代码不展开：直接使用 Unicode 字符。
• 示例文案：内置中文 GFM 清单示例，用于第一眼展示表格与任务列表，不是 lorem。
• 与博客站渲染的关系：本站博客 MDX 序列化同样挂了 remark-gfm（见 pages/blog/[slug].tsx），因此表格在博文与预览工具上的方言一致；但博客还走 MDX/JSX 规则（正文里裸的小于号可能被当成 JSX），写博文时另有约束，与本工具的纯 Markdown 字符串路径不同。

FAQ

Markdown 和 HTML 可以混用吗？

许多平台允许 Markdown 中夹 HTML。本站预览工具不会把源码里的裸 HTML 当成可执行页面片段来渲染；要得到 HTML 字符串请用 互转工具，嵌入自有站点前再做消毒。

文件扩展名是什么？

常见 .md / .markdown。GitHub、GitLab 等会对仓库内 .md 做渲染。

支持数学公式吗？

标准 Markdown / 本站预览都不内置 KaTeX/MathJax。需要公式时在目标平台启用相应插件，或导出后再渲染。

数据和预览会上传吗？

预览逻辑在浏览器本地执行。视图偏好等会写入本地存储；共享电脑用完可清站点数据或换无痕窗口。

为什么表格在编辑器里「对齐了」预览却坏了？

先数分隔行管道数量是否与列数一致，再查单元格是否有未转义的 |。源码空格对齐错误通常不影响渲染；列数不一致才会。

延伸阅读

• HTML ↔ Markdown 指南 — Turndown / marked 往返损耗与表格陷阱
• Markdown 表格生成器指南 — 对齐语法与生成器行为
• YAML ↔ JSON 指南 — 文档里贴配置时的序列化差异
• JSON 格式化指南 — 代码块示例前的规范化
• 文本 Diff 指南 — 两版 Markdown/配置对照
• HTML 实体编码指南 — 把文本安全放进 HTML 时的转义

ToolVault 工具匣 出品的开发者指南。首页 汇集了更多浏览器本地工具。