Markdown 转 Jira：把笔记贴进工单不再满屏井号

我第一次在 Jira 里写工单描述时踩了个坑：把 GitHub 上写好的 PR 正文整段复制过去，渲染出来满屏都是 ## 和 **，标题没成标题，粗体也没成粗体。后来才知道，Jira 的描述框和评论框压根不认 Markdown，它讲的是另一套叫 wiki markup 的语法。两套语法长得像，规则却处处不一样，靠手改既慢又容易漏。

Jira 为什么用 wiki 标记而不是 Markdown

Jira 这套 wiki markup 比 Markdown 成为通用默认还要早。它的文本框渲染的是 h2. 这样的标题记号、*粗体* 这样的加粗记号，跟 Markdown 完全是两个体系。新版云端编辑器确实加了类 Markdown 的输入模式，但各个实例之间不一致，遇到代码块和表格就开始乱。最稳的做法是先把 Markdown 转成 wiki 标记，再粘进工单，这样在任何 Jira 实例里渲染都一样。

标题：井号变成 h 加数字

Markdown 的标题靠数前面有几个井号，Jira 则用 h1. 到 h6. 这种带点的记号。一个具体的点要记牢：Jira 的标题写成 h1. 标题，注意 h、数字、点之后还有一个空格，少了那个空格 Jira 就不认。

对照很直接：

Markdown            Jira wiki 标记
# 标题              h1. 标题
## 小节             h2. 小节
### 子节            h3. 子节

有些人为了对称在结尾也补井号，比如 ## 完成 ##，转的时候那些结尾井号要去掉，留下干净的 h2. 完成。

粗体和斜体:记号正好对调

这是最容易翻车的地方,因为两套语法的符号含义正好错位。

Markdown 粗体 **已发布**,在 Jira 里要写成 *已发布*,单个星号在 wiki 标记里就是粗体。
Markdown 斜体 *备注* 或 _备注_,在 Jira 里统一写成 _备注_,下划线才是斜体。
删除线 ~~旧的~~ 变成 -旧的-,单个连字符。

顺序也有讲究:必须先处理双星号的粗体,再处理单星号的斜体,不然一个 **词** 会被先吃掉一对星号,转出来串味。

代码块和表格

行内代码 ` npm run build 在 Jira 里是 {{npm run build}},双花括号表示等宽。围栏代码块从三个反引号变成 {code:js} 开头、{code} 收尾的面板;不带语言的围栏就是普通的 {code}`。代码里的星号、井号都原样透传,不会被当成格式。

表格差异最大。Markdown 的竖线表格有一行虚线分隔行,Jira 没有这东西。转换时要把分隔行整行丢掉,表头单元格改成双竖线:| 名字 | 角色 | 变成 ||名字||角色||,正文行保持单竖线 |阿达|工程师|。那个双竖线表头正是 Jira 标记表格标题的写法。

一个真实的转换例子

把这段 Markdown 笔记贴进工单前,先过一遍转换:

输入(Markdown):

# 发布说明
**改动**:修了登录超时。运行 `pnpm test` 验证。

输出(Jira wiki 标记):

h1. 发布说明
*改动*:修了登录超时。运行 {{pnpm test}} 验证。

可以看到 # 标题 转成了 h1. 标题,双星号粗体收成单星号,行内代码套上了双花括号。这一整段直接粘进 Jira 描述框,渲染出来就是真标题、真粗体、真等宽代码,而不是一堆裸符号。

这些规则我以前是靠肉眼一处处改的,改十几行就头大,还总漏掉斜体的下划线。后来全部交给 Markdown 转 Jira 工具,左边贴 Markdown,右边实时出 wiki 标记,点一下复制就能贴进工单,整个过程在浏览器里跑,内部的故障复盘或没发布的规格都不会离开机器。

反过来和别的格式

如果你要的是把 Markdown 渲染成网页预览看效果,可以用 Markdown 转 HTML 工具对照着看结构。手头的格式如果不是 Markdown 而是别的,也先转成 Markdown 再走这一步,链路会顺很多。

把 Markdown 笔记搬进 Jira 这件小事,卡住人的从来不是内容,而是两套标记符号的错位。记住三条:标题是 h加数字加点加空格,单星号是粗体,表格表头用双竖线,大部分工单粘进去就不会再坏掉了。

Made by Toolora · Updated 2026-06-13