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 在全站唯一,一旦建立就無法更改。發布時間同樣無法事後修改。用錯誤的內容發布出去就收不回来,所以请把結果當成草稿,用預覽看過之後再發布。