Markdown 轉 HTML：乾淨的發佈工作流 | Toolars

發佈管線需要一種能熬過工具、託管平台與重新設計的主格式。純文字 Markdown 就是這個主版本：任何編輯器都能讀，版本控制裡差異清晰，與今年用來渲染它的 HTML 範本無關。

可攜可攜性：Markdown 檔案在任何編輯器中都能開啟，無需遷移工程即可轉換為 HTML、PDF、投影片或文件系統。
可比對可審閱：文字改動呈現為乾淨的行級差異；而 HTML 主版本會把一個詞的修改埋在標籤與屬性裡。
結構而非樣式關注點分離：來源檔只承載結構——標題、清單、引文——排版交給主題決定，重新設計永遠不會觸碰存檔。

有意為之的轉換器只支援一個子集，因為每多支援一種構造，就多一條夾帶未經審閱標記的通道。在依賴轉換之前，先弄清你的內容相對這條線的位置。

乾淨轉換乾淨轉換：最多六級標題、段落、粗體、斜體、刪除線、行內程式碼、圍欄程式碼區塊、有序與無序清單、區塊引文、分隔線與行內連結。
已知損失被壓平或丟棄：嵌入圖片、表格、註腳、任務清單與原始 HTML 區塊在子集中沒有對應表示，因此會消失或退化為純文字。
用真實文章測試測試方法很簡單：轉換一篇有代表性的文章並閱讀輸出。結果裡缺的東西，從來都不在契約裡。

轉換出的 HTML 注定要被注入頁面，而被注入的標記就是攻擊面。乾淨的管線預設清理：腳本、樣式、iframe、表單、嵌入與圖片一律移除，未知標籤解包為文字，屬性全部剝除。

移除主動內容攜帶主動行為的元素——script、style、iframe、object、embed、svg、form、video、audio、img——連同內容一起移除，而不只是被中和。
剝除屬性屬性整體消失：沒有行內樣式、沒有事件處理器、沒有從來源夾帶的類別名。錨點只在通過協定檢查時保留 href。
報告而非靜默工作區會報告移除了什麼——被丟棄節點與被剝屬性的計數——清理是可見事件，而不是靜默改動。

渲染出的文件大部分是連結，而連結正是清理最講究的地方。轉換器只接受 http、https 與 mailto 位址以及頁內 #片段；其餘——javascript:、data:、協定相對的把戲——都會失去 href，渲染為純文字。

協定白名單存活的連結會被蓋上 rel="noreferrer noopener"，被點開的連結無法看到或操控開啟它的頁面。
noopener noreferrer同一規則雙向適用：Markdown 裡寫的連結在轉換時檢查，貼上的 HTML 裡的 href 在清理後重新檢查。
標籤文字保留當連結失去協定時，標籤文字仍在——壞掉的導覽立即可見，而不是把一個靜默的 javascript: 酬載帶進發佈。

把 HTML 轉回 Markdown 是搶救，不是往返。子集理解的結構——標題、段落、強調、清單、引文、程式碼——能完好回來；其餘的在轉換開始之前就被清理器丟棄了。

表格塌縮表格塌縮：子集沒有表格語法，一格一格的網格會變成一串儲存格文字，表格資料需要重寫或改用 CSV 匯出。
媒體被移除圖片、影片與互動嵌入按設計消失——在產生 Markdown 之前，清理器已把它們作為主動內容移除。
文字比樣式長壽子集之外的格式——span、div、類別名、錨點目標——不留痕跡；文字倖存，樣式不倖存。

轉換在發佈時執行，每篇文章一次：用 Markdown 起草與審閱，轉換成清理過的 HTML，核驗渲染結果，然後發佈。一切都在瀏覽器分頁裡發生——草稿從不上傳，這在內容屬於未公開的發佈時尤其重要。

發佈時執行工作區接受最大 256 KiB 的來源文字，產出最大 512 KiB 的輸出——足夠一本書的章節規模——超過限制時會報出明確的錯誤，而不是靜默截斷。
明確的上限把輸出複製進 CMS 欄位，或下載為檔案；兩條路徑拿到的都是預覽中那份清理過的文件。
重新轉換，別打補丁把 Markdown 和它記錄的程式碼一起放進版本控制，每次修改後重新轉換，而不是修補舊 HTML。