我從2018年開(kāi)始正式用 Markdown 寫(xiě)博客到現(xiàn)在發(fā)布了大概三百多篇文章分發(fā)到掘金、博客園、公眾號(hào)、知乎、CSDN 這些平臺(tái)。頭半年真是踩坑踩到懷疑人生本地渲染得好好的表格粘貼進(jìn)知乎就碎成渣圖片路徑用了相對(duì)路徑傳到博客園全部裂開(kāi)公眾號(hào)那邊更絕代碼塊縮進(jìn)整個(gè)被吃掉格式像車(chē)禍現(xiàn)場(chǎng)。后來(lái)我慢慢把整套流程捋順了現(xiàn)在一篇 markdown 博客從定稿到發(fā)布到四五個(gè)平臺(tái)基本控制在半小時(shí)以?xún)?nèi)。這篇我就把整套實(shí)戰(zhàn)工作流拆開(kāi)來(lái)講包括寫(xiě)作環(huán)境怎么搭、核心語(yǔ)法怎么適配各平臺(tái)奇葩規(guī)則、圖片路徑怎么處理、哪些環(huán)節(jié)可以用腳本和工具半自動(dòng)化最后附一份我自己的排查速查表。適合正在用或者準(zhǔn)備用 Markdown 寫(xiě)博客、又被多平臺(tái)發(fā)布折磨過(guò)的朋友不管你是剛上手的博客新人還是已經(jīng)寫(xiě)了幾年但還在手動(dòng)復(fù)制粘貼的老作者這篇應(yīng)該都能幫你省下不少時(shí)間。1. 為什么我堅(jiān)持用 Markdown 寫(xiě)博客1.1 從“復(fù)制粘貼排版”到“一次編寫(xiě)處處分發(fā)”先說(shuō)說(shuō)我為什么非得用 Markdown。早期我直接在平臺(tái)的富文本編輯器里寫(xiě)寫(xiě)完存草稿換平臺(tái)發(fā)就得重新排版——標(biāo)題大小、加粗、代碼塊、引用樣式全平臺(tái)各不相同煩得我一度不想寫(xiě)博客。Markdown 最大的價(jià)值是可移植性一份純文本源稿Git 管理起來(lái)干凈可以在任何編輯器里打開(kāi)也可以被任何腳本處理。它把內(nèi)容從格式里解放出來(lái)了。但必須明確一點(diǎn)Markdown 源稿雖然是純文本但各平臺(tái)對(duì) Markdown 的渲染規(guī)則從來(lái)不是一套標(biāo)準(zhǔn)。GitHub 風(fēng)格的 Markdown 和掘金的 Markdown 就有差異公眾號(hào)和知乎甚至還談不上原生支持。所以“一次編寫(xiě)處處分發(fā)”不是免費(fèi)的午餐它需要你配上一層適配邏輯。這篇文章講的其實(shí)就是這層適配邏輯怎么搭。1.2 多平臺(tái)發(fā)布的真實(shí)痛點(diǎn)清單我總結(jié)了一下幾乎所有 Markdown 多平臺(tái)發(fā)布的痛點(diǎn)就集中在五個(gè)方面換行規(guī)則不同導(dǎo)致段落間距、強(qiáng)制換行在不同平臺(tái)渲染結(jié)果完全不同圖片路徑依賴(lài)本地相對(duì)路徑換平臺(tái)發(fā)布就裂開(kāi)表格在各平臺(tái)兼容性極差復(fù)制后列錯(cuò)位、邊框丟失代碼塊的高亮語(yǔ)言、行號(hào)、縮進(jìn)在不同平臺(tái)支持程度不一樣數(shù)學(xué)公式、Callout 這類(lèi)進(jìn)階語(yǔ)法很多平臺(tái)直接不認(rèn)這五個(gè)點(diǎn)任何一個(gè)沒(méi)處理好發(fā)布效果都會(huì)打折扣。后面我會(huì)逐一展開(kāi)說(shuō)怎么解決。1.3 一條主線(xiàn)源文件 適配層 發(fā)布動(dòng)作我在長(zhǎng)期實(shí)踐中把工作流收斂成一條主線(xiàn)源文件、適配層、發(fā)布動(dòng)作。源文件就是那篇 md 草稿永遠(yuǎn)只維護(hù)一份適配層是幾個(gè)固定動(dòng)作——圖片轉(zhuǎn)圖床、表格轉(zhuǎn)兼容格式、代碼塊語(yǔ)言標(biāo)記、公式轉(zhuǎn)圖片發(fā)布動(dòng)作則是把適配后的版本復(fù)制到目標(biāo)平臺(tái)。這條主線(xiàn)聽(tīng)起來(lái)很簡(jiǎn)單但每一步都有細(xì)節(jié)。比如適配層不是每次都從頭手動(dòng)做而是根據(jù)目標(biāo)平臺(tái)執(zhí)行不同的“規(guī)則包”發(fā)布到掘金執(zhí)行 A 組規(guī)則發(fā)布到公眾號(hào)執(zhí)行 B 組規(guī)則。這個(gè)思路很像編譯原理里的“目標(biāo)代碼生成”不同后端對(duì)應(yīng)不同指令集。理解了主線(xiàn)后面的實(shí)操就不是背步驟而是按需組裝。2. 寫(xiě)作環(huán)境搭建編輯器、插件與目錄規(guī)劃2.1 編輯器選型Typora、VS Code、Obsidian 怎么選寫(xiě)作環(huán)境是我最早折騰的事。Typora 和 VS Code 是問(wèn)得最多的兩個(gè)選擇加上 Obsidian這三者覆蓋了大多數(shù)人的需求。Typora 走的是所見(jiàn)即所得路線(xiàn)寫(xiě)出來(lái)的渲染效果和最終網(wǎng)頁(yè)非常接近對(duì)博客作者最直觀(guān)。我目前主用的就是 Typora理由很簡(jiǎn)單它把 Markdown 的“所見(jiàn)即所得”做到了極致表格、代碼塊、圖片拖拽這些高頻操作手感很好。要說(shuō)缺點(diǎn)它本身不管理知識(shí)庫(kù)也不適合做復(fù)雜腳本處理。VS Code 適合作者本身是程序員的情況配合 Markdown All in One、markdownlint 等插件能實(shí)現(xiàn)目錄樹(shù)、快捷鍵、格式檢查、導(dǎo)出 PDF 等能力。我可以直接在 VS Code 里寫(xiě)文章順便用 Git 管理版本寫(xiě)完跑腳本批量處理圖片路徑一條龍下來(lái)很順手。Obsidian 更適合把博客文章當(dāng)成個(gè)人知識(shí)庫(kù)的一部分雙鏈、標(biāo)簽、圖譜這些功能對(duì)長(zhǎng)期積累內(nèi)容很有價(jià)值。但它的 Markdown 有一些私有語(yǔ)法發(fā)布時(shí)要注意厘清別把[[雙鏈]]的語(yǔ)法留在草稿里導(dǎo)致平臺(tái)發(fā)布時(shí)出現(xiàn)亂碼。編輯器核心優(yōu)勢(shì)短板適合人群Typora所見(jiàn)即所得、輕量不支持插件擴(kuò)展內(nèi)容創(chuàng)作者、非技術(shù)博主VS Code插件生態(tài)強(qiáng)、可跑腳本預(yù)覽與編輯分離程序員、技術(shù)博客作者Obsidian知識(shí)管理、雙向鏈接私有語(yǔ)法多筆記型、長(zhǎng)期積累的博主2.2 必裝插件與關(guān)鍵配置不管用哪個(gè)編輯器有幾個(gè)配置我建議拿到手先改。Typora 用戶(hù)在“偏好設(shè)置”里務(wù)必檢查三件事勾選“Markdown 擴(kuò)展語(yǔ)法”里的數(shù)學(xué)公式和任務(wù)列表把圖片插入路徑設(shè)為“復(fù)制到 ./assets 文件夾”避免圖片散落桌面打開(kāi)“代碼塊語(yǔ)法高亮”并且語(yǔ)言識(shí)別保持開(kāi)啟VS Code 用戶(hù)我推薦直接安裝這三個(gè)插件Markdown All in One補(bǔ)全、目錄、快捷鍵、markdownlint格式規(guī)范檢查、Markdown Preview Enhanced高級(jí)預(yù)覽和導(dǎo)出。裝完以后寫(xiě)稿時(shí)右下角就不會(huì)一直飄紅線(xiàn)了一些小錯(cuò)誤在源頭就能攔下來(lái)。2.3 目錄結(jié)構(gòu)與草稿管理寫(xiě)作目錄這一塊很多人不在意但我踩過(guò)一次大坑之后就開(kāi)始嚴(yán)格執(zhí)行規(guī)范了。我的整個(gè)博客工程目錄是這樣組織的blog/ source/ 2025-01-15-markdown多平臺(tái)發(fā)布指南.md ... assets/ markdown-launch/ image-01.png image-02.png exports/ juejin/ wechat/ blog-cn/ scripts/ replace-img-path.py export-markdown.py命名規(guī)則是日期-簡(jiǎn)短標(biāo)題.mdassets 下面按文章建子目錄圖片統(tǒng)一放在這里源稿和圖片都在 Git 倉(cāng)庫(kù)里管理。這樣帶來(lái)的直接好處是遷移、回滾、生成平臺(tái)定制版本都很方便不會(huì)出現(xiàn)“圖片在哪”這種靈魂拷問(wèn)。如果你已經(jīng)寫(xiě)了挺久但目錄亂成一鍋粥我建議找一個(gè)周末專(zhuān)門(mén)重構(gòu)一次長(zhǎng)期收益非常大。3. 核心語(yǔ)法與格式適配最容易翻車(chē)的地方3.1 換行為什么段落總是擠在一起先講最常見(jiàn)也最容易被忽略的換行問(wèn)題。Markdown 標(biāo)準(zhǔn)里段落之間必須用一個(gè)空行分隔否則即使寫(xiě)了換行渲染時(shí)也會(huì)被合并成一段。而“行尾加兩個(gè)空格強(qiáng)制換行”這個(gè)規(guī)則在 Typora 里顯示正常但粘貼到掘金、知乎這類(lèi)平臺(tái)兩個(gè)空格會(huì)被吃得很隨意最終效果就是行沒(méi)換、段落全擠成一坨。我的做法簡(jiǎn)單粗暴寫(xiě)正文段落時(shí)絕不在段內(nèi)使用行尾兩個(gè)空格做強(qiáng)制換行分段一律用空行如果確實(shí)需要短行排列比如列舉步驟每步單獨(dú)一行就使用無(wú)序列表或者有序列表而不是靠換行撐排版。這樣至少能保證大多數(shù)平臺(tái)的渲染結(jié)果和本地預(yù)覽一致。另外手機(jī)上寫(xiě)協(xié)作文檔時(shí)往往習(xí)慣直接回車(chē)分段這類(lèi)文本復(fù)制到博客平臺(tái)同樣會(huì)因?yàn)槿笨招卸みB粘貼前最好先全局檢查一遍空行結(jié)構(gòu)。3.2 圖片路徑三步走相對(duì)路徑、圖床、CDN圖片路徑是我發(fā)布流程里最早被解決的問(wèn)題。用相對(duì)路徑./assets/markdown-launch/image-01.png在本地一切正常但文章發(fā)布到平臺(tái)后圖片地址沒(méi)有對(duì)應(yīng)的域名和目錄自然全部裂開(kāi)。所以正確路線(xiàn)是三步本地圖片統(tǒng)一放 assets 目錄發(fā)布前上傳到圖床換取 HTTPS 鏈接如果圖片量大建議再掛一層 CDN 做加速和縮放。圖床選型上我試過(guò) PicGo 配合七牛云、阿里云 OSS、又拍云也用過(guò)一些免費(fèi)圖床。最后固定下來(lái)的是 PicGo 自有對(duì)象存儲(chǔ)核心考慮是穩(wěn)定性——免費(fèi)圖床省了錢(qián)但域名隨時(shí)可能被墻、被防盜鏈哪天圖片全成 xxx 就很難受。PicGo 的優(yōu)勢(shì)是可以自定義上傳路徑和 URL 規(guī)則批量上傳后自動(dòng)生成 Markdown 格式的鏈接直接復(fù)制替換原稿里的相對(duì)路徑就行。批量替換時(shí)我寫(xiě)過(guò)一個(gè)簡(jiǎn)單的 Python 腳本本質(zhì)是讀 md 文件、正則匹配、替換成幾十篇文章批量處理也就幾秒鐘。還有個(gè)容易被忽視的點(diǎn)圖片文件名中的中文和空格在任何 CDN 上大概率會(huì)產(chǎn)生編碼問(wèn)題。建議上傳前統(tǒng)一改成小寫(xiě)英文 數(shù)字短橫線(xiàn)風(fēng)格例如multi-platform-publish-01.png。這個(gè)習(xí)慣能避免一批莫名其妙的 404。3.3 表格兼容性復(fù)制過(guò)去為什么列全錯(cuò)亂表格是另一個(gè)重災(zāi)區(qū)。本地 Typora 里畫(huà)好的表格看著很整潔復(fù)制到知乎專(zhuān)欄可能整個(gè)表格結(jié)構(gòu)就散架了粘貼到公眾號(hào)后臺(tái)要么邊框全丟要么變成一串 HTML 代碼。原因是很多平臺(tái)富文本編輯器對(duì) Markdown 表格的“管道符 橫線(xiàn)”語(yǔ)法渲染有限復(fù)制時(shí)只會(huì)復(fù)制純文本無(wú)法還原表格結(jié)構(gòu)。我在多次實(shí)測(cè)后定下這樣幾條規(guī)則發(fā)布到掘金、CSDN、博客園這類(lèi)技術(shù)平臺(tái)直接用原生 Markdown 表格它們普遍支持良好發(fā)布到知乎、公眾號(hào)這類(lèi)平臺(tái)改用 HTML 形式的table表格粘貼后能保留結(jié)構(gòu)表格列數(shù)超過(guò) 6 列或者內(nèi)容過(guò)多時(shí)直接導(dǎo)出成圖片可讀性遠(yuǎn)勝任何文本表格另外表格和 Excel 又是另一個(gè)場(chǎng)景。有時(shí)候我在 Typora 里排好的表格同事想要 Excel 版本Typora 本身提供了“復(fù)制為表格內(nèi)容”直接粘貼到 Excel 的功能但這不是博客發(fā)布場(chǎng)景別把它和平臺(tái)粘貼混淆了。我做了一個(gè)小工具腳本可以把任何一個(gè) Markdown 表格解析成 HTML 表格字符串輸出發(fā)布前拷貝過(guò)去效果很穩(wěn)定。3.4 代碼塊高亮和縮進(jìn)的隱藏規(guī)則代碼塊看起來(lái)簡(jiǎn)單實(shí)際發(fā)布時(shí)細(xì)節(jié)很多。首先是語(yǔ)言標(biāo)記千萬(wàn)別偷懶不寫(xiě)python和裸的在所有平臺(tái)上的高亮效果完全不同。我習(xí)慣在每段代碼上標(biāo)語(yǔ)言并且只在少數(shù)支持附加屬性的平臺(tái)如博客園使用python {titlexxx.py lineNumberstrue}這類(lèi)寫(xiě)法換到其他平臺(tái)會(huì)先去掉附加屬性防止渲染錯(cuò)誤。更隱蔽的問(wèn)題是公眾號(hào)。公眾號(hào)編輯器對(duì) Markdown 代碼塊里的空格和縮進(jìn)支持極差直接粘貼時(shí)前導(dǎo)空格可能被吃掉代碼整體左縮進(jìn)或歪掉。我通常會(huì)用專(zhuān)門(mén)工具做一次“Markdown 轉(zhuǎn)公眾號(hào) HTML”把代碼塊包進(jìn)precode標(biāo)簽再粘貼到公眾號(hào)后臺(tái)。粘貼完后一定要點(diǎn)開(kāi)預(yù)覽檢查縮進(jìn)和轉(zhuǎn)義字符這一步省不了。3.5 數(shù)學(xué)公式與 GitHub Callout 等進(jìn)階語(yǔ)法進(jìn)階語(yǔ)法這里我說(shuō)一下數(shù)學(xué)公式和 Callout 的適配。數(shù)學(xué)公式目前主流寫(xiě)法是$行內(nèi)公式$和$$塊級(jí)公式$$。Typora 默認(rèn)開(kāi)啟了數(shù)學(xué)擴(kuò)展后本地體驗(yàn)很好但發(fā)布時(shí)可惜的是掘金、CSDN 和博客園支持度尚可知乎是半殘狀態(tài)公眾號(hào)則完全不能渲染。我的妥協(xié)方案是涉及復(fù)雜公式的場(chǎng)景直接導(dǎo)出一個(gè)公式截圖或者 SVG 文件作為圖片插入正文。這在視覺(jué)上傳真度接近原版又規(guī)避了各平臺(tái)渲染引擎差異。Callout 是 GitHub 風(fēng)格的強(qiáng)調(diào)塊寫(xiě)法是 [!NOTE]、 [!WARNING]。這種語(yǔ)法在 GitHub 上很棒但能在博客平臺(tái)渲染出來(lái)的少之又少。我自己的策略是如果目標(biāo)平臺(tái)不支持 Callout就在源稿里把這類(lèi)塊改寫(xiě)為普通引用塊 加粗標(biāo)題效果不差還更通用。高級(jí)語(yǔ)法和通用語(yǔ)法之間要做取舍優(yōu)先保底線(xiàn)兼容。3.6 不同渠道的特定格式公眾號(hào)、釘釘、微博除了傳統(tǒng)博客平臺(tái)很多人還會(huì)把 Markdown 內(nèi)容同步到公眾號(hào)甚至用釘釘機(jī)器人發(fā)一些消息通知。公眾號(hào)那邊我見(jiàn)過(guò)有人硬搬 Markdown 文本進(jìn)去出來(lái)的效果基本不能看。正確做法是先用 md2wechat 這類(lèi)工具把文章轉(zhuǎn)成帶內(nèi)聯(lián)樣式的 HTML再粘貼到公眾號(hào)編輯器。轉(zhuǎn)換后的標(biāo)題、引用、代碼塊、列表樣式都不太需要二次調(diào)整我只用再手動(dòng)處理一下分割線(xiàn)和圖片注釋。釘釘?shù)摹邦A(yù)警”和“消息卡片”是另一個(gè)常見(jiàn)場(chǎng)景。釘釘?shù)?Markdown 消息格式和博客 Markdown 不是一回事它支持## 標(biāo)題、- 列表、**加粗**這些基礎(chǔ)語(yǔ)法但不支持圖片和復(fù)雜表格代碼塊也是受限的。我之前踩過(guò)一次坑把一份完整技術(shù)文章往釘釘機(jī)器人推送結(jié)果變成了純文本堆疊。后來(lái)我調(diào)整了做法釘釘消息只放要點(diǎn)摘要正文附鏈接格式清爽多了。微博就更特殊了原生發(fā)布器不支持 Markdown一般有兩種處理短期通告類(lèi)內(nèi)容直接轉(zhuǎn)成長(zhǎng)圖發(fā)布如果是正經(jīng)技術(shù)文章建議用網(wǎng)頁(yè)版一些支持 Markdown 轉(zhuǎn)長(zhǎng)圖的小工具生成一張高清長(zhǎng)圖。圖片可以完整保留代碼高亮和代碼塊樣式體驗(yàn)可以接受但要注意長(zhǎng)圖寬高比別太夸張。4. 多平臺(tái)發(fā)布實(shí)操流程從定稿到分發(fā)4.1 主流平臺(tái) Markdown 支持度對(duì)比先把主流平臺(tái)的 Markdown 支持情況列成一張表這是我實(shí)測(cè)下來(lái)比較公允的結(jié)論僅供參考平臺(tái)規(guī)則更新后可能要微調(diào)平臺(tái)原生 Markdown代碼高亮數(shù)學(xué)公式表格兼容備注掘金好好支持好粘貼體驗(yàn)較好CSDN較好好支持一般標(biāo)題、圖片需檢查博客園好好支持較好可自定義樣式知乎部分支持一般半殘差建議 HTML 表格簡(jiǎn)書(shū)好較好不支持一般代碼塊正常公眾號(hào)不支持不支持不支持差必須用轉(zhuǎn)換工具思否好好支持好相對(duì)省心這個(gè)表的核心價(jià)值是輔助判斷發(fā)布到哪個(gè)平臺(tái)該走哪條適配規(guī)則。我一般把平臺(tái)分成兩類(lèi)一類(lèi)是“原生容器”比如掘金、博客園、思否規(guī)則簡(jiǎn)單一類(lèi)是“富文本容器”比如公眾號(hào)、知乎必須經(jīng)過(guò)一層轉(zhuǎn)換。4.2 手動(dòng)發(fā)布的黃金步驟如果你還沒(méi)接自動(dòng)化手動(dòng)發(fā)布也可以很穩(wěn)。我現(xiàn)在每次發(fā)布都按下面這套順序走基本不會(huì)漏掉檢查項(xiàng)本地 Typora 打開(kāi)源稿先跑一遍 markdownlint 修復(fù)格式問(wèn)題用 PicGo 批量上傳文章內(nèi)所有圖片替換 md 中的圖片路徑針對(duì)目標(biāo)平臺(tái)執(zhí)行對(duì)應(yīng)的適配規(guī)則表格轉(zhuǎn) HTML、公式轉(zhuǎn)圖、Callout 改寫(xiě)將適配后的完整 Markdown 復(fù)制到平臺(tái)的 Markdown 編輯器發(fā)布前預(yù)覽重點(diǎn)看圖片、代碼高亮、表格、標(biāo)題層級(jí)發(fā)布后打開(kāi)線(xiàn)上文章頁(yè)面再快速掃一遍格式回到源稿把圖片路徑更新為圖床鏈接提交 Git 存檔第 7 步很多人不做我強(qiáng)烈建議養(yǎng)成習(xí)慣。否則源稿和線(xiàn)上版本不一致下次想改版重發(fā)會(huì)發(fā)現(xiàn)圖片全是相對(duì)路徑又得重新查一遍。4.3 各平臺(tái)的適配細(xì)節(jié)實(shí)錄針對(duì)幾個(gè)重點(diǎn)平臺(tái)我說(shuō)幾個(gè)實(shí)測(cè)細(xì)節(jié)。掘金是當(dāng)前支持 Markdown 比較省心的平臺(tái)直接把適配后的文本粘貼進(jìn)去就行唯一要注意的是文章封面圖需要單獨(dú)上傳正文里的首圖容易因?yàn)槁窂絾?wèn)題被折疊。博客園自由度最高它甚至允許自定義 CSS我一般會(huì)把代碼塊的字體、背景微調(diào)成自己習(xí)慣的樣式但要注意主題之間的兼容。知乎那邊表格和圖片是兩大軟肋。表格我全部轉(zhuǎn)成tableHTML 后粘貼實(shí)測(cè)結(jié)構(gòu)穩(wěn)定圖片用圖床鏈接且要勾選“保存到知乎圖集”否則部分移動(dòng)端場(chǎng)景會(huì)出現(xiàn)防盜鏈提示。公眾號(hào)這里再?gòu)?qiáng)調(diào)一次任何所謂“公眾號(hào) Markdown 編輯器”本質(zhì)都是把 Markdown 轉(zhuǎn)成內(nèi)聯(lián)樣式 HTML你只管排版不用理解它內(nèi)部的那些按鈕。發(fā)布后最好用手機(jī)預(yù)覽一下因?yàn)楹芏鄻邮皆?PC 后臺(tái)看是正常的手機(jī)上段間距、字體大小才會(huì)露餡。CSDN 情況稍微特殊它對(duì) Markdown 支持其實(shí)不錯(cuò)但平臺(tái)會(huì)默認(rèn)給你插入一些推廣內(nèi)容和“目錄生成”占位發(fā)布前要把這些額外內(nèi)容檢查掉有時(shí)文章開(kāi)頭會(huì)有非 Markdown 語(yǔ)法導(dǎo)致的標(biāo)題錯(cuò)位需要手動(dòng)修正一級(jí)標(biāo)題。4.4 半自動(dòng)與自動(dòng)化實(shí)踐腳本、工具鏈與 Coze 工作流如果你文章量大建議做半自動(dòng)化。我目前的半自動(dòng)流程是這樣的PicGo 負(fù)責(zé)圖片上傳和鏈接生成一個(gè) Python 腳本負(fù)責(zé)批量替換 md 里的圖片路徑另一個(gè)腳本負(fù)責(zé)把文章按目標(biāo)平臺(tái)拆成不同導(dǎo)出版本最后配合一個(gè)本地快捷鍵工具把適配后的文本一鍵復(fù)制到剪貼板。隨著現(xiàn)在大模型工作流工具變多用 Coze 這類(lèi)平臺(tái)搭“Markdown 轉(zhuǎn) Word”或者“Markdown 格式化”工作流也成了不少人的選擇。我自己搭過(guò)一個(gè)簡(jiǎn)單的工作流輸入 md 文本調(diào)用 API 返回 HTML再輸出到指定格式。這個(gè)思路適合做中轉(zhuǎn)和批處理但要注意格式損耗——每次自動(dòng)化轉(zhuǎn)換都可能引入新的奇怪空格或字符跑完后一定人工抽查。拿它做常用格式的預(yù)處理可以指望它全自動(dòng)完美發(fā)布以我目前測(cè)過(guò)的效果還不現(xiàn)實(shí)。5. 常見(jiàn)問(wèn)題排查與避坑實(shí)錄5.1 表格粘貼后列錯(cuò)位、邊框丟失出現(xiàn)這個(gè)問(wèn)題的原因幾乎是固定的平臺(tái)富文本編輯器把 Markdown 表格當(dāng)純文本粘貼或者只識(shí)別了一部分管道符。解決方法是粘貼前把 Markdown 表格改成 HTMLtable字符串再粘貼。在知乎和公眾號(hào)上我測(cè)試過(guò) 30 列以上的大表格用 HTML 標(biāo)簽基本不會(huì)錯(cuò)位。如果一定要用原生 Markdown 表格只建議發(fā)掘金這種原生支持好的平臺(tái)。5.2 圖片加載不出來(lái)大概率三種原因圖片還是相對(duì)路徑、圖床域名被防盜鏈、上傳后圖片被壓縮導(dǎo)致路徑變化。我個(gè)人排查順序是先看瀏覽器直接訪(fǎng)問(wèn)圖床鏈接是否 200再看站點(diǎn)是否加了防盜鏈 Referer 限制最后檢查 md 里是不是有中文路徑未編碼。對(duì)了本地相對(duì)路徑改圖床鏈接時(shí)記得把./前綴去掉否則拼接 URL 時(shí)會(huì)多出一段相對(duì)路徑。5.3 代碼縮進(jìn)被吃掉、高亮失效公眾號(hào)是最常見(jiàn)的縮進(jìn)殺手。處理辦法前面提過(guò)用precode包裹代碼。高亮失效則多是因?yàn)榇a塊語(yǔ)言標(biāo)識(shí)沒(méi)寫(xiě)或者平臺(tái)對(duì)python linenums1這類(lèi)擴(kuò)展語(yǔ)法不識(shí)別。我的辦法是統(tǒng)一使用純語(yǔ)言標(biāo)記不給自己加戲。高亮行號(hào)如果平臺(tái)原生不支持就不要強(qiáng)求至少代碼本身要整齊。5.4 數(shù)學(xué)公式變成亂碼或整段消失公式亂碼十有八九是行內(nèi)公式$...$被平臺(tái)當(dāng)成了普通文本過(guò)濾或轉(zhuǎn)義。解決方案有三個(gè)改用塊級(jí)$$...$$發(fā)布后檢查還是不行就轉(zhuǎn)成圖片最不濟(jì)直接改為文字化描述。就我的經(jīng)驗(yàn)技術(shù)博客如果沒(méi)有極端的公式需求能用“x 的平方”這類(lèi)文字表達(dá)的就盡量用文字渲染問(wèn)題直接繞開(kāi)。5.5 排查速查表癥狀可能原因處理方案段落黏連缺少空行分段加空行行內(nèi)強(qiáng)制換行失效依賴(lài)了兩個(gè)空格換行改用列表或空行圖片全部裂開(kāi)相對(duì)路徑/防盜鏈圖床 URL 檢查 Referer表格錯(cuò)位平臺(tái)不兼容 Markdown 表格改用 HTML 表格代碼縮進(jìn)丟失富文本壓縮空格用pre包裹后粘貼代碼高亮失效未寫(xiě)語(yǔ)言或擴(kuò)展語(yǔ)法不被識(shí)別只寫(xiě)python公式亂碼平臺(tái)不支持$語(yǔ)法使用塊級(jí)公式或轉(zhuǎn)圖釘釘消息樣式混亂使用了博客語(yǔ)法只用基礎(chǔ)語(yǔ)法 摘要6. 實(shí)測(cè)工作流我的一次真實(shí)發(fā)布過(guò)程6.1 從寫(xiě)稿到發(fā)布的標(biāo)準(zhǔn)動(dòng)作我舉一個(gè)實(shí)際例子。假設(shè)今天要寫(xiě)一篇《用 Python 寫(xiě)爬蟲(chóng)的 5 個(gè)提醒》平臺(tái)目標(biāo)是掘金、公眾號(hào)、知乎。我的流程是這樣的在 Typora 寫(xiě)稿assets 目錄建python-crawler-tips/子目錄插圖全部拖進(jìn)去。寫(xiě)完跑一遍 markdownlint確認(rèn)標(biāo)題層級(jí)只有 H1/H2/H3無(wú) H4 以上跳躍。打開(kāi) Typora 偏好設(shè)置里的“復(fù)制 Markdown 源碼”功能先把整篇復(fù)制到剪貼板然后以 Markdown 源稿為基線(xiàn)依次做三份導(dǎo)出掘金版直接粘貼源稿圖片替換成圖床鏈接發(fā)布后花兩分鐘過(guò)一遍標(biāo)題和代碼。公眾號(hào)版跑一遍 md2wechat 轉(zhuǎn)換把輸出粘貼到公眾號(hào)編輯器再用手機(jī)預(yù)覽確認(rèn)樣式。知乎版在源稿基礎(chǔ)上把表格全部替換成 HTML 表格公式部分轉(zhuǎn)成圖片粘貼前又特意檢查了一遍代碼塊語(yǔ)言標(biāo)記。整個(gè)過(guò)程加起來(lái)大概 40 分鐘其中真正花在“格式適配”上的時(shí)間不超過(guò) 10 分鐘剩下的時(shí)間都用在內(nèi)容打磨上。6.2 我最終留下的工具清單最后整理一份我現(xiàn)在每天用的工具清單供參考分類(lèi)工具用途替代方案編輯器Typora 1.11.x寫(xiě)作與本地預(yù)覽VS Code、Obsidian格式檢查markdownlint修正語(yǔ)法規(guī)范IDE 自帶校驗(yàn)圖片上傳PicGo 對(duì)象存儲(chǔ)圖床鏈接生成iPic、路過(guò)圖床表格轉(zhuǎn)換自寫(xiě) Python 腳本Markdown 表格轉(zhuǎn) HTML在線(xiàn)轉(zhuǎn)換工具公眾號(hào)轉(zhuǎn)換md2wechatMarkdown 轉(zhuǎn)公眾號(hào) HTMLMarkdown Nice版本管理Git GitHub源稿存檔與回溯堅(jiān)果云、本地備份6.3 回頭看的一些個(gè)人選擇回頭看這七八年折騰下來(lái)的經(jīng)驗(yàn)我最大的體會(huì)是不要迷信任何“一鍵發(fā)布全平臺(tái)”的工具。各平臺(tái)的編輯器和渲染規(guī)則是動(dòng)態(tài)變化的今天好用的插件明天可能就失效了。相比之下一套基于 Markdown 源稿 明確適配規(guī)則 少量腳本的流程反而最穩(wěn)定因?yàn)樗巡淮_定的部分拆開(kāi)來(lái)了每塊都可以獨(dú)立測(cè)試和修正。如果你正準(zhǔn)備從富文本切換到 Markdown 流程別貪心先只跑一個(gè)平臺(tái)試試跑通后再把其他平臺(tái)映射進(jìn)來(lái)。這套東西的核心價(jià)值不是省那點(diǎn)復(fù)制粘貼的時(shí)間而是讓你對(duì)每次發(fā)布的格式有確定性預(yù)期——知道哪個(gè)環(huán)節(jié)可能出問(wèn)題、出了問(wèn)題去哪修。這是我無(wú)論如何都不想放棄它的原因。