Markdown 转 Textile 标记:把文档迁进 Redmine 的语法对照笔记

我们组的工单系统是 Redmine。每次我把在 GitHub 上写好的 PR 说明,直接粘进 Redmine 的问题描述框,出来的总是一屏井号和星号,看着像页面坏了。后来才搞明白,Redmine 描述框解析的根本不是 Markdown,而是一种叫 Textile 的标记语言。两边结构对得上,只是记号不一样,这篇就把差异讲清楚,顺便记下我自己迁文档的流程。

Textile 到底是什么

Textile 是一种轻量标记语言,出现得比 Markdown 还早。它至今仍是 Redmine、老版 Trac、基于 RedCloth 的 Ruby 站点,还有好几个 wiki 的原生格式。它的设计目标跟 Markdown 一样:让人用纯文本写出带格式的内容,再渲染成 HTML。区别只在标点:Markdown 用开头的井号标题,Textile 用 h1. 这种带点的记号;Markdown 行内代码是反引号,Textile 是 at 符号。

如果你们团队在 Redmine 里跟踪问题,描述框和评论框认的都是 Textile。原样粘进去的 Markdown 会停在字面上的井号和星号,不会渲染。这就是为什么迁文档之前得先转一遍。

标题的差异:用 h1. 加一个点

这是两种语言差得最明显的地方。Markdown 数开头有几个井号决定标题级别,Textile 则用字母 h 加数字再加一个点。

具体规则是:一个井号 # 标题 变成 h1. 标题,两个井号 ## 小节 变成 h2. 小节,一直到 h6.。注意那个点和后面的空格不能少,Textile 靠它们识别这是个标题行,而不是普通段落。有些人为了对称会在标题结尾也补几个井号,转换时这些尾部井号会被去掉,## 完成 ## 仍然得到干净的 h2. 完成。

粗体斜体删除线:星号的含义反了

这里有个特别容易踩的坑。Markdown 里双星号 **粗体** 才是加粗,但在 Textile 里单个星号就是粗体,两个星号反而会在两边各多渲染一个裸星号。所以 **已发布** 要转成单星号片段。

斜体也对不上:Markdown 用单星号或下划线写斜体 *备注*,而 Textile 里下划线才表示斜体,所以它会变成下划线片段。删除线 ~~旧的~~ 在 Textile 里是单连字符片段,写成 -旧的-。转换要先处理双记号的粗体再处理单记号的斜体,否则 snake_case 这种带下划线的词会被串味。

链接图片代码块:三个高频结构

链接的写法整个换了个个儿。Markdown 把文字放方括号、网址放圆括号;Textile 给文字加引号,再跟一个冒号和裸网址。图片则是用感叹号包住网址,alt 文字会被丢掉,因为 Textile 是靠网址本身认这张图的,这跟 Redmine 渲染附件的方式一致。

代码方面,行内代码从反引号换成 at 符号,` git push 变成 @git push@。围栏块从三反引号换成 bc. 块,里面的代码原样透传,语言标签会被去掉,因为朴素的 bc.` 形式在各个 Redmine 版本之间最通用。

一个真实的转换例子

把这段 Markdown 丢进左边输入框:

# 发布说明
**已发布** v2.1,详见 [文档](https://docs.example.com)。
运行 `git pull` 拉取更新。

右边的 Textile 实时变成:

h1. 发布说明
*已发布* v2.1,详见 "文档":https://docs.example.com。
运行 @git pull@ 拉取更新。

标题 # 发布说明 转成了 h1. 发布说明,双星号粗体收成了单星号,链接换成引号加冒号的写法,行内代码套上了 at 符号。这一段粘进 Redmine 问题,渲染出来就是规规整整的标题、加粗和等宽命令,而不是一堆裸符号。

把这件事做成日常流程

我现在的做法很省事:不管是 PR 正文、README 片段,还是大模型给的 Markdown 答案,先整段过一遍 Markdown 转 Textile 工具,复制结果再贴进 Redmine wiki 或工单。整个转换在浏览器标签页里跑,内部的故障报告或还没发布的规格都不会离开我的机器,这点对工作内容来说很关键。

如果你的目标系统不是 Redmine 而是 Jira,那 Jira 用的又是另一套标记,可以改用 Markdown 转 Jira 工具;要是只想把 Markdown 渲染成普通网页,Markdown 转 HTML 工具 更直接。结构都对得上,挑对目标格式的工具,一遍就能转干净。

---

Made by Toolora · Updated 2026-06-13