Qiita / Zenn 兼容性检查工具
Qiita 和 Zenn 是日本的开发者写作平台,两边的 Markdown 方言并不相同。把文章粘贴进来,可以提前找出发布之后才会暴露的问题。能一对一对应的部分会自动转换,但结果只是草稿。
粘贴文章的 Markdown。连同 frontmatter 一起放进来,也会检查标题和标签。
能做和不能做的事
- 能检出的是整理好的 74 处差异。自动转换 37 处,需要人判断的 14 处,没有对应写法的 23 处。
- Zenn 不渲染 raw HTML。Qiita 文章里常用的 details 折叠、img 的宽度指定、dl 定义列表,在 Zenn 里不会报错,而是把标签字符串原样显示在正文里。
- 有 21 处差异既不报错也不警告就坏掉。这类只能在发布后的页面上看出来,请以预览确认为前提。
- 没有运行 Qiita 那边的渲染器。关于在 Qiita 最终如何显示的判断,依据的是官方文档和实现代码的阅读。
- 处理的只有正文和 frontmatter 的文本。不会搬运或上传图片文件,粘贴的内容不会离开浏览器。
关于 Qiita 与 Zenn 的写法差异
这个工具做的是诊断
Qiita 和 Zenn 是日本开发者发文章的两个主要平台,两边接受的都是各自加了扩展的 Markdown。两者之间整理出来的差异有 74 处。其中有一对一对应、能机械转换的是 37 处。剩下的是需要人来决定往哪边靠的 14 处,以及目标平台根本没有对应写法的 23 处。自动转换只用在这 37 处,其余只做指出和给出选项。
Zenn 不渲染 HTML
Zenn 的渲染器以默认配置使用 markdown-it,不放行 raw HTML。因此 Qiita 文章里常见的 details 折叠、指定了宽度的 img、dl 定义列表,在 Zenn 里不会报错,而是把标签字符串原样显示给读者。构建能通过,也没有警告,所以只能在发布后才发现。这类差异有 21 处。
note 和 message 不是一对一
Qiita 的 note 块有 info / warn / alert 三个级别,而 Zenn 的 message 只有默认和 alert 两个级别。把 warn 原样写成 :::message warn 不会变成块,那串字符会显示在正文里。这个工具会让你选 warn 往默认还是 alert 靠,而不擅自决定。
Zenn → Qiita 方向在结构上更安全
Qiita 放行 raw HTML,所以 Zenn 特有的写法可以换成 HTML 搬过去。丢掉的是代表 emoji、发布时间这类只有 Zenn 才有的 frontmatter,Qiita 本来就不用。事故比反方向少,但 Qiita 上的显示没有用这个工具实测过,确认同样是必要的。
发布前务必确认显示效果
Zenn 的 slug 在全站唯一,一旦创建就无法更改。发布时间同样无法事后修改。用错误的内容发布出去就收不回来,所以请把结果当成草稿,用预览看过之后再发布。