Markdown 是寫文件、筆記和部落格常用的輕量標記格式,用#寫標題、-寫列表、反引號寫程式碼,很多靜態網站還在檔案開頭用 front matter 寫標題、日期等資訊。整份直接轉換,會把程式碼裡的變數名、連結裡的中文路徑一起改掉,程式碼出錯、連結失效。這個頁面先識別 Markdown 的結構,只轉換給人讀的部分。
會轉換的內容
- 正文、標題、列表、表格和引用。
- 連結文字和圖片的 alt 文字。
- front matter 裡的值。
- 指向標題的頁內連結,跟著標題一起轉換。
- 內嵌 HTML 標籤裡的 title、alt 等文字屬性。
保持不變的內容
- 圍欄程式碼區塊、縮排程式碼區塊和行內程式碼;程式碼區塊裡的註解可選轉換,預設不轉。
- 連結和圖片的網址,包括中文路徑。
- front matter 的鍵名和 HTML 標籤本身。
亂碼與編輯器相容
Markdown 編輯器和靜態網站生成器通常按 UTF-8 讀取檔案。GBK 或 Big5 編碼的舊文件會被自動識別並轉成 UTF-8。換行字元保持原樣,BOM 預設跟隨原檔案,所以原檔案是 UTF-8 時,用 Git 比較前後版本,差異只出現在轉換過的文字上。
轉換範例
| 原文 | 結果 |
|---|---|
| ## 安装说明 | ## 安裝說明 |
| 请先阅读[使用文档](docs/使用文档.md)。 | 請先閱讀[使用文檔](docs/使用文档.md)。 |
| 运行 `npm install 软件包` 安装依赖。 | 運行 `npm install 软件包` 安裝依賴。 |
|  |  |
| | 名称 | 说明 | | | 名稱 | 說明 | |
| - **注意**:后台程序会自动更新。 | - **注意**:後臺程序會自動更新。 |
由 OpenCC(s2t)實際轉換生成。
怎麼用
- 把 .md 或 .markdown 檔案拖到頁面上,或點「選擇檔案」,一組文件可以一次選多個。
- 選方向和標準;面向臺灣讀者的文件可以選「臺灣」,「轉換地區用詞」預設開啟,技術用語會換成臺灣說法。
- 需要時展開「各格式的進階選項」,決定是否轉換程式碼區塊裡的註解。
- 核對預覽後下載,多個檔案可以點「全部下載(ZIP)」。
注意事項
- 轉換地區用詞時,技術詞也會換成當地說法,例如「程序」轉成「程式」、「文件」轉成「檔案」。「文件」表示公文、書面材料時也會這樣轉,技術文件請通讀一遍。
- 一簡多繁的字單獨出現時可能選錯,檔案裡不會標註。沒把握的段落可以貼上到「文字」標籤檢視待確認字。
- 連結網址原樣保留,例如 docs/使用文档.md。一組互相連結的文件,下載時檔名請選「保持原名」,否則加了語言字尾的檔名和連結對不上。
常見問題
程式碼區塊裡的中文會被轉換嗎?
不會。圍欄程式碼區塊、縮排程式碼區塊和行內程式碼都保持原樣,變數名和字串不受影響。程式碼區塊裡的註解預設也不轉,可以在進階選項裡開啟「Markdown:也轉換程式碼區塊裡的註解」。
目錄裡的頁內連結還能用嗎?
能。指向標題的頁內連結會跟著標題一起轉換,例如[安装](#安装)會變成[安裝](#安裝),和轉換後的標題對得上。
front matter 會被改成什麼樣?
鍵名不變,只轉換值,例如標題和摘要;值是路徑或網址時保持原樣。
文件裡的 HTML 標籤怎麼處理?
標籤本身保持不變,其中的 title、alt 等文字屬性會轉換。