Markdown 转 Confluence：把 MD 笔记贴进公司 Wiki 的完整做法

我第一次把一段写好的 Markdown 发布说明粘进 Confluence 页面时，整页显示的是 ## 上线清单 和 **注意** 这样的字面字符，井号和星号一个没少。那一刻我才搞明白，Confluence 页面默认根本不渲染原始 Markdown，它认的是另一套东西：Atlassian 的旧版 wiki 标记。要让一段 Markdown 真正落地成标题、代码块、表格，你得先把它翻译成 wiki 标记，再走插入，标记，Wiki Markup 这条菜单。

下面把语法差异和迁移流程讲清楚，省得你像我当初那样对着满屏星号发呆。

Confluence 为什么不直接吃 Markdown

新版 Confluence 编辑器确实能在你输入时识别一部分 Markdown，但这个能力在 Cloud，Server，Data Center 三种部署之间表现并不一致。一旦遇到代码块，表格，嵌套列表，识别就会乱掉。真正稳定的路子是旧版 wiki 标记：它在哪个版本渲染都一样。你需要做的，是先把 Markdown 改写成 wiki 标记，再通过插入，标记，Wiki Markup 粘进去。

标题的对应：从井号到 h1.

这是最直观的一处差异。Markdown 用井号数量表示层级，Confluence 用 h 加数字。一个具体例子：

输入（Markdown）：

# 标题
## 小节

输出（Confluence wiki 标记）：

h1. 标题
h2. 小节

规则就是数前面有几个井号，写出 h 加那个数字，再跟一个点和一个空格。深到 h6. 为止。结尾为了对称多打的井号会被去掉，所以 ## 完成 ## 转出来是干净的 h2. 完成。

代码块用花括号 code，不是反引号

Markdown 里围栏代码块用三个反引号开头，Confluence 这边换成花括号写法。带语言的围栏块，比如标了 js 的，转成 {code:js} 开头，用 {code} 收尾；不带语言的就是普通 {code} 块。块里的内容原样透传，代码样例里的星号或井号永远不会被当成格式误解析。

行内代码也不一样：Markdown 的单反引号 ` npm run build ，到 Confluence 变成双花括号的 {{npm run build}}` 等宽记号。

表格为什么是双竖线表头

Markdown 的竖线表格有表头行，虚线分隔行，正文行三部分。转换时分隔行直接丢掉，表头单元格改写成双竖线，正文行用单竖线。也就是说 | 名字 | 角色 | 变成 ||名字||角色||，正文行 |阿达|工程师| 保持单竖线。双竖线表头正是 Confluence 标注表格标题的写法，渲染出来才是带粗体表头的真表格，而不是一堆散落的竖线字符。

Confluence 和 Jira 的引用差异

这两套标记大部分通用，同样的 h1. 标题，*粗体*，_斜体_，{{等宽}}，{code} 代码块。唯一明显的分叉在引用：Jira 给每一行引用加 bq. 前缀，Confluence 则把整段引用包进 {quote} 块。所以一连串引用行，Confluence 会输出成单独一行的 {quote}，接着是各行内容，再用 {quote} 收尾。如果你的目标是 Jira，请换用 /zh/t/markdown-to-jira/ ，它用的是 bq. 那种写法。

团队文档迁移的实操建议

我们组把一批 README 和发布说明从仓库搬进团队空间时，靠的就是 /zh/t/markdown-to-confluence/ 这个转换器。整个流程在浏览器标签页里以纯 JavaScript 跑，不上传任何内容，一次粘贴出结果，再一键复制。几条经验：

第一，别把原始 Markdown 直接粘进 Confluence 页面就指望它渲染，它只会显示字面字符，先转换再走插入，标记，Wiki Markup。第二，多级子列表的缩进未必能原样保留，Confluence 用重复标记符表示层级，粘进去后核对一下深层列表。第三，wiki 标记是旧版功能，有些较新的 Cloud 站点把这个入口藏在管理员设置后面，启用后才能用。

如果你的目标格式不是 Confluence，相邻几种转换也常用得上：写技术文档可以看 reStructuredText 方向的转换，或者直接转成网页用的 HTML。需要把现成网页内容反向收进笔记时，反过来的转换同样现成。

把语法差异记牢，迁移就从反复手敲变成一次粘贴的事。

Made by Toolora · Updated 2026-06-13