寫技術(shù)文檔這幾年我?guī)缀趺刻於荚诟?Markdown 打交道。無論是寫項(xiàng)目說明、整理筆記、發(fā)博客還是給團(tuán)隊(duì)寫內(nèi)部協(xié)作文檔Markdown 都是我首選的寫作格式。它看似簡單——幾個符號、幾行標(biāo)記卻能解決內(nèi)容排版里最煩人的那批問題字號不統(tǒng)一、樣式復(fù)制失敗、換個平臺格式就亂。我見過不少剛接觸的人的第一反應(yīng)是這玩意兒不就是幾個 # 和 * 嗎有什么好學(xué)的。但實(shí)際用上一段時間就會發(fā)現(xiàn)越基礎(chǔ)的東西越值得把細(xì)節(jié)摳清楚。這一篇我不打算寫教科書式的條目匯編而是以一個日常使用者的角度把 Markdown 基礎(chǔ)語法里最常用的那部分講透順便聊聊哪些地方容易踩坑、為什么這么寫、以及怎么根據(jù)自己的習(xí)慣搭一套順手的寫作流程。如果你正在學(xué) Markdown或者已經(jīng)用了一段時間但總感覺有些地方不順手這篇文章會很適合你。內(nèi)容會覆蓋設(shè)計思路、核心語法、實(shí)操中的各種細(xì)節(jié)、常見問題排查、還有不同平臺的兼容性差異。我不保證講完全部冷門用法但我可以保證讀完你會對標(biāo)注、嵌套、表格、代碼塊這些常用操作心里有底寫起來不再猶豫。1. 從設(shè)計思路說起Markdown 為什么是純文本聊語法之前我想先說說 Markdown 的底層邏輯。很多人直接上手學(xué)符號學(xué)會了卻總在奇怪的地方卡殼本質(zhì)上就是沒搞懂它為什么要做成現(xiàn)在這個樣子。1.1 極簡標(biāo)記專注內(nèi)容本身Markdown 的核心思想其實(shí)特別樸素我寫的是一份帶標(biāo)記的純文本文件而不是一份“排版好的文檔”。傳統(tǒng)編輯器的做法是你一邊輸入內(nèi)容一邊定義它的格式——選中文字、點(diǎn)按鈕、調(diào)字體、改顏色。聽起來很直觀但實(shí)際帶來的問題是你的注意力一直被格式牽引真正的內(nèi)容反而不那么連貫了。Markdown 反過來它把排版需要的信息用幾個字符直接寫進(jìn)文本里。想寫個大標(biāo)題就在行首放一個#想讓某個詞加粗就用兩個星號把它包起來。這樣做的第一個好處是寫作的時候手不需要離開鍵盤不需要去點(diǎn)任何菜單思路不會被打斷。第二個好處更加實(shí)際因?yàn)樗羌兾谋灸愀静挥脫?dān)心格式會丟。不管把這個文件拿到什么編輯器、什么系統(tǒng)、什么設(shè)備上打開內(nèi)容本身永遠(yuǎn)都是完整的。1.2 一次編寫處處轉(zhuǎn)換我記得最早接觸 Markdown 的時候有個疑問光寫純文本怎么轉(zhuǎn)成那種排版精美的頁面后來才明白Markdown 的渲染思路其實(shí)是“中間層”。你寫的是帶標(biāo)記的源文件外面套一層轉(zhuǎn)換引擎就能把它變成 HTML、PDF、Word、微信公眾號格式等各種各樣的輸出。這種思路很像寫代碼的人常說的一句話數(shù)據(jù)與展示分離。你用統(tǒng)一的標(biāo)記語言寫好數(shù)據(jù)展示層可以隨時換皮膚。同一個 Markdown 文件放在代碼托管平臺上是帶高亮的源碼風(fēng)格放在筆記軟件里是清爽干凈的閱讀風(fēng)格放到博客系統(tǒng)里又是完全不一樣的主題樣式。如果換作傳統(tǒng)編輯器輸出的文檔你得為每個平臺重新排版一遍操心字體大小、圖片位置、行間距這些工作本身和內(nèi)容創(chuàng)作毫無關(guān)系純粹是消耗精力。1.3 通用性帶來長期價值讓我真正堅定用 Markdown 的是它的通用性。我這些年積攢下來的筆記和文檔有幾百篇中間換過好幾款筆記軟件、博客平臺、協(xié)作工具但從來沒有遇到過內(nèi)容遷移的問題。原因很簡單Markdown 是純文本只要有文本編輯器就能打開它有統(tǒng)一的基本約定幾乎所有平臺都支持解析。而這些約定簡單到不可能徹底失效。這其實(shí)也解釋了為什么很多簡歷、開源項(xiàng)目說明、技術(shù)博客、甚至?xí)某醺宥荚谟?Markdown。它不是某個獨(dú)立軟件創(chuàng)造出來的私有格式而是一種事實(shí)標(biāo)準(zhǔn)用戶的選擇成本很低轉(zhuǎn)移的代價也極低。所以我建議每個剛開始寫作的人不管寫的是技術(shù)文章還是日常生活記錄都可以從 Markdown 入手。它給你的不是一套排版方案而是一種穩(wěn)定、可靠、能長期跟著你走的寫作方式。2. 基礎(chǔ)語法拆解每個標(biāo)記都學(xué)明白這一節(jié)會進(jìn)入實(shí)用層面。我不打算把語法一條條列完就收工那樣的話網(wǎng)上隨便找張速查表就夠用了。我想在講每個標(biāo)記的同時把背后容易忽略的細(xì)節(jié)、常見誤區(qū)一并說出來這樣你學(xué)習(xí)的時候能少走一些彎路。2.1 標(biāo)題注意空格別吞字標(biāo)題是最高頻的語法之一寫法是行首加#從一級到六級依次對應(yīng) 1 到 6 個井號。但這里有個很多人一開始就忽略的點(diǎn)#和標(biāo)題文字之間要加一個空格。比如# 一級標(biāo)題 ## 二級標(biāo)題 ### 三級標(biāo)題加了空格之后渲染器才明確知道井號是標(biāo)記符號而不是標(biāo)題內(nèi)容的一部分。如果你寫#核心功能在部分平臺里它可能被識別成標(biāo)題也可能把#直接當(dāng)成文字輸出表現(xiàn)不一致。這種不一致一旦出現(xiàn)在你交付的文檔里結(jié)果很難看。標(biāo)題的層級邏輯也需要提前想清楚。一級標(biāo)題在一個頁面里最好只有一個類似文章總題二級標(biāo)題是章節(jié)三級、四級往下依次細(xì)分。不要跳過層級比如從二級直接跳到四級渲染效果雖然不會報錯但閱讀結(jié)構(gòu)會很亂尤其在生成目錄時跳級會導(dǎo)致目錄結(jié)構(gòu)斷裂。實(shí)操里我的習(xí)慣是正文常駐二級標(biāo)題章節(jié)內(nèi)部用三級遇到特殊情況才用四級。這個習(xí)慣能保證整篇文檔的結(jié)構(gòu)清楚、不過度嵌套。另外標(biāo)題下面建議空一行再接正文即使不空也能渲染但空一行對 Markdown 源碼的可讀性非常有幫助尤其是別人拿到你的源文件時一眼能分清結(jié)構(gòu)。2.2 強(qiáng)調(diào)語法星號與下劃線的差別強(qiáng)調(diào)包括加粗、斜體和刪除線它們是行內(nèi)文字排版最常見的需求。加粗是一對雙星號或雙下劃線**加粗文字** __也可以加粗__斜體是單星號或單下劃線*斜體文字* _也可以斜體_刪除線是用兩個波浪號包起來~~刪除內(nèi)容~~這里有一個非常值得說的細(xì)節(jié)同一種效果星號和下劃線幾乎是等效的但我的實(shí)際推薦是盡量統(tǒng)一使用星號。原因是下劃線在英文里有時會和單詞本身混淆比如_hello_world_這種形式有些渲染器會把它理解成斜體標(biāo)記而更多情況下閱讀源碼時會覺得奇怪。星號沒有這種困擾。強(qiáng)調(diào)符號里還有一個常見誤區(qū)符號和文字之間不能有空格。比如** 加粗 **在不少平臺上渲染不出來因?yàn)榍昂蠖嗔丝崭窠馕銎鲿醋置婵崭窨创?。正確寫法是符號與文字緊貼不加空格。另外嵌套強(qiáng)調(diào)時要注意配對順序比如加粗里面嵌斜體可以寫**這是加粗里的 *斜體* 文字**星號的配對是逐層的寫反了會漏掉一部分效果。2.3 列表有序和無序的差異與嵌套列表是整理信息的利器分無序列表和有序列表兩種。無序列表只要在行首加-、*或后面跟一個空格再接內(nèi)容例如- 第一項(xiàng) - 第二項(xiàng) - 第三項(xiàng)有序列表是數(shù)字加英文句點(diǎn)加空格1. 第一步 2. 第二步 3. 第三步這里容易出問題的是兩個地方。第一有序列表的數(shù)字不需要連續(xù)正確。你可以全部寫1.渲染時它會自動按順序遞增。這其實(shí)是個很實(shí)用的技巧因?yàn)槟阍谡{(diào)整條目順序時不需要手動改序號只要保證條目順序?qū)托袖秩境鰜硎冀K是 1、2、3、4。第二列表嵌套需要縮進(jìn)。子列表要在父列表項(xiàng)下面另起一行并且縮進(jìn)兩個或四個空格具體看平臺。嵌套例子- 分類一 - 子項(xiàng) A - 子項(xiàng) B - 分類二如果縮進(jìn)不對子列表會被拍平變成平級條目整個結(jié)構(gòu)的層級感就沒了。我踩過不少次這個坑后來養(yǎng)成了一個習(xí)慣凡寫嵌套列表都會在源碼里刻意檢查縮進(jìn)是否整齊。你可能會問為什么非要在源碼層面較真因?yàn)?Markdown 源碼的整潔度決定了后期維護(hù)的難度現(xiàn)在嫌檢查麻煩以后改結(jié)構(gòu)時更麻煩。2.4 引用多層次嵌套與實(shí)用場景引用在 Markdown 里用右尖括號表示通常用于轉(zhuǎn)述他人觀點(diǎn)、引用文獻(xiàn)片段、或者突出強(qiáng)調(diào)某段重要說明。基本寫法 這是一個引用塊引用塊可以嵌套引用塊內(nèi)部再寫一個就能嵌套二級引用這在逐層追溯信息來源時非常好用 外層引用 內(nèi)層引用引用塊還可以包含其他元素比如標(biāo)題、列表、代碼塊。它們只需要在引用內(nèi)部按普通 Markdown 語法編寫即可。比如 ## 引用內(nèi)的標(biāo)題 - 列表?xiàng)l目一 - 列表?xiàng)l目二 這是正文。寫引用時要注意每個引用行最好都以開頭哪怕中間有空行也要寫成空行的形式。有些平臺允許“懶寫法”即只要段落第一行有后續(xù)幾行不寫也算引用內(nèi)但換來換去容易出錯。我個人的習(xí)慣是每行都帶一勞永逸。引用還有一個思路上的應(yīng)用很多人會忽略寫教程或提示信息時拿引用塊裝“注意事項(xiàng)”比用普通段落醒目得多。尤其在一個較長文檔里讀者快速掃視時眼睛會優(yōu)先注意到引用塊的顏色變化這其實(shí)是閱讀體驗(yàn)上的一種引導(dǎo)技巧。2.5 鏈接與圖片路徑和尺寸都要上心鏈接的基本語法是[顯示文字](目標(biāo)地址)例如[我的博客](https://example.com)鏈接可以分為外部鏈接和相對鏈接。外部鏈接指向完整的網(wǎng)址相對鏈接指向本地文件在寫項(xiàng)目說明時非常常用。比如你在文檔里引用同目錄下的另一份文檔可以寫[開發(fā)指南](docs/guide.md)這樣點(diǎn)擊時可以直接跳轉(zhuǎn)到該文件。圖片語法只比鏈接多一個感嘆號這里我特別想提醒三件事第一替代文字不是隨便寫的。它用于圖片加載失敗時顯示的文字也是無障礙閱讀和搜索引擎識別圖片內(nèi)容的依據(jù)。認(rèn)真的文檔里替代文字應(yīng)當(dāng)簡明描述圖片內(nèi)容像“登錄頁面截圖”“架構(gòu)圖”這樣而不是空著或?qū)懸淮畞y碼。第二相對路徑的寫法要非常小心。如果你用 Markdown 寫項(xiàng)目文檔并存放圖片推薦在項(xiàng)目里建一個assets或images文件夾文中引用時使用相對路徑比如。如果直接用絕對路徑文檔從一臺電腦拷到另一臺電腦時圖片就全部失效。你也不能依賴網(wǎng)絡(luò)圖床鏈接外部鏈接一旦失效文檔里就是一堆碎圖。第三Markdown 原生的圖片語法不支持設(shè)置寬度、高度、居中。想調(diào)圖片尺寸常用的方案是直接使用 HTML 的img標(biāo)簽像這樣img srcassets/screenshot.png width60% /幾乎所有的 Markdown 渲染器都允許混入 HTML。這個特性在普通文本里用得少但在寫正式文檔時用處不小我們后面還會專門聊。2.6 表格注意管道符與對齊表格是 Markdown 基礎(chǔ)語法里最“有脾氣”的一部分。它用管道符|分隔列用一行短橫線作為表頭與內(nèi)容的分隔行?；A(chǔ)寫法| 功能 | 快捷鍵 | 適用場景 | | ---- | :---: | -------: | | 加粗 | CtrlB | 強(qiáng)調(diào)重點(diǎn) | | 斜體 | CtrlI | 引入名詞 | | 刪除線 | ~~ | 標(biāo)記廢棄 |第二行| ---- |是分隔行它還承擔(dān)著對齊方式的任務(wù)。冒號在左邊表示左對齊兩邊都有冒號表示居中冒號在右邊表示右對齊。上面的示例里“功能”沒有冒號即默認(rèn)左對齊“快捷鍵”是居中“適用場景”是右對齊。表格最容易踩的坑是管道符周圍的空格。Markdown 解析表格時依賴管道符來區(qū)分列所以每一行管道符數(shù)量必須相同。如果你某一行少了一個管道符整個表格就會渲染異常有時甚至?xí)?dǎo)致后續(xù)內(nèi)容全部變成表格的一部分亂成一團(tuán)。我見過不少人為了美觀把表格里的內(nèi)容用大量空格對齊。這種美化其實(shí)完全沒有必要因?yàn)殇秩境鰜砜吹氖亲罱K表格源碼里的空格只是輔助解析的渲染器會自動忽略多余的空白。與其花時間對齊源碼不如保證每一行管道符數(shù)量一致內(nèi)容緊貼管道符即可。2.7 分割線三個符號的安全寫法分割線用三個或以上的-、*、_獨(dú)行書寫即可--- *** ___這里有一個老手才知道的坑---不光是分割線它還有可能是二級標(biāo)題的另一種寫法。在 Markdown 里任何一段文字下面緊跟一行---都會被解析成二級標(biāo)題。比如我的標(biāo)題 ---這樣寫的后果是“我的標(biāo)題”會被渲染成二級標(biāo)題而不是正文上方的分割線。想避免這種歧義可以在分割線上下都保留空行并且盡量讓分割線前后不要緊貼著正文段落。最穩(wěn)妥的做法是分割線單獨(dú)成段和上下文都隔一個空行。很多編輯器在你寫---后會自動補(bǔ)出空行就是在規(guī)避這個問題。3. 代碼與代碼塊寫技術(shù)內(nèi)容的必備姿勢如果一定要我選出 Markdown 語法里最值錢的一部分我可能會把票投給代碼相關(guān)的語法。它讓 Markdown 成了寫技術(shù)文檔的標(biāo)準(zhǔn)語言。3.1 行內(nèi)代碼反引號的配對魔法行內(nèi)代碼用于在普通句子中提到變量名、函數(shù)名、命令等。用單個反引號包住內(nèi)容即可這里需要執(zhí)行 git commit 命令。行內(nèi)代碼的樣式通常是等寬字體加底色和正文有明顯區(qū)分。它和普通文字最大的區(qū)別是內(nèi)部的符號不會被當(dāng)作 Markdown 語法解析。比如你想在文章里寫*不重要*如果直接放在正文里會把文字變成斜體如果放在反引號里就能原樣輸出星號和文字。但反引號本身也有一個坑如果內(nèi)容里恰好需要用到反引號怎么辦比如你想在文章里寫“使用 符號表示行內(nèi)代碼”這時候外層包裹的反引號會和內(nèi)層反引號沖突。解決辦法是加長邊界反引號用兩個反引號包裹一個反引號例如 這個是反引號同理內(nèi)容里如果有兩個連續(xù)反引號外層就可以用三個。理解了邊界加長的思路這部分就不難了。3.2 圍欄代碼塊別忘記標(biāo)注語言多行代碼塊使用三個反引號包裹也可以使用三個波浪號。前一種寫法更常見也是我的首選。圍欄代碼塊最大的優(yōu)勢是可以指定編程語言讓渲染器做語法高亮function hello() { console.log(Hello, Markdown!); }圍欄代碼塊是一把雙刃劍高度靈活但也容易出錯。最常見的錯誤是忘記關(guān)閉三個反引號結(jié)果后面的所有內(nèi)容全部被當(dāng)成了代碼直到下一個三個反引號出現(xiàn)代碼塊才結(jié)束。這種錯誤的特征是排版突然變成等寬字體、所有 Markdown 標(biāo)記全部失效。排查時只要上下找找漏掉的那行圍欄就行。另一個常見問題是語言標(biāo)注寫錯。不寫語言標(biāo)注并不影響渲染但會失去高亮閱讀體驗(yàn)差一截。標(biāo)注語言時用規(guī)范的小寫名稱比如javascript、python、bash、json不同平臺支持的語法高亮器略有差異但通用名基本都能識別。3.3 縮進(jìn)代碼塊老式寫法的優(yōu)缺點(diǎn)除了圍欄代碼塊還有一種更原始的方式每行前縮進(jìn)四個空格或一個制表符。這是一個縮進(jìn)代碼塊 內(nèi)容放在四個空格之后 第二行也在縮進(jìn)里這種寫法的優(yōu)點(diǎn)是簡潔缺點(diǎn)也很明顯無法指定語言高亮在列表里很難控制縮進(jìn)層級。如果你在列表項(xiàng)里需要再放代碼塊縮進(jìn)會變得層層疊疊極易出錯。所以現(xiàn)在的主流平臺幾乎都不再推薦這種寫法了但你在閱讀老文檔時還是可能會遇到需要知道它是什么。我的原則很簡單能用圍欄代碼塊就不用縮進(jìn)代碼塊尤其是寫正式文檔時可讀性和高亮效果都明顯更好。4. 搭建日常寫作流程編輯、渲染與管理學(xué)會了標(biāo)記語法之后真正決定效率的是工作流。不會用工具語法學(xué)得再熟也白搭。這一節(jié)我會講講怎么圍繞 Markdown 搭建一套順手的工作流包括編輯器選擇、圖片管理、目錄生成和版本沉淀。4.1 編輯器選擇思路市面上的 Markdown 編輯器很多各有偏向但選擇時主要看三條編輯體驗(yàn)、渲染預(yù)覽、擴(kuò)展能力。如果你追求所見即所得可以選那些“實(shí)時渲染”型的編輯器左側(cè)是源碼右側(cè)是渲染預(yù)覽也有的編輯器直接輸入即渲染光標(biāo)所在行顯示源碼其他行顯示效果。這類編輯器對新手很友好犯錯時會立刻看到異常效果調(diào)試起來快。如果你更喜歡代碼風(fēng)格可以考慮用代碼編輯器加 Markdown 插件的方式。這樣做的優(yōu)勢是你只需要熟悉一個編輯器就夠不用在多個工具之間切來切去而且代碼編輯器里的 Git 集成、文件樹、全局搜索等能力都很成熟對管理一大套文檔非常順手。如果你是重度筆記用戶那就直接選一款筆記軟件。它們通常自帶云同步、全文檢索、標(biāo)簽體系這些功能對寫零散知識記錄很有幫助。不管選哪類我都建議你一定試一下它的導(dǎo)出能力有的工具導(dǎo)出 PDF 時樣式混亂有的導(dǎo)出圖片會丟相對路徑這些問題在選定工作流之前發(fā)現(xiàn)比等到交付文檔時才措手不及要好得多。4.2 圖片文件管理方案圖片是文檔里最容易出問題的一環(huán)。我早期寫文檔時喜歡直接把圖片拖進(jìn)編輯器編輯器會自動生成一份本地文件但目錄結(jié)構(gòu)一團(tuán)糟圖片名字也是隨機(jī)生成的根本看不出哪張圖對應(yīng)哪段內(nèi)容。后來我固定了一套方案每個項(xiàng)目建立獨(dú)立的目錄如assets/圖片命名要有語義比如login-dialog-error.png文中引用一律使用相對路徑如同一項(xiàng)目內(nèi)所有相對路徑以項(xiàng)目根目錄為基準(zhǔn)文件夾移動時同步調(diào)整這套辦法看起來很簡單但它解決了一個真實(shí)痛點(diǎn)項(xiàng)目變多以后你不需要打開圖片看內(nèi)容光看文件名和引用位置就能知道文檔在說什么。對協(xié)同伙伴來講也友好他們拿到整個項(xiàng)目文件夾打開文檔時所有圖片都能正常顯示不需要額外問路徑。4.3 生成目錄和錨點(diǎn)跳轉(zhuǎn)有些寫作場景要求開頭有個目錄結(jié)構(gòu)尤其是長文檔。Markdown 生成目錄有兩種方式自動和手動。自動目錄由渲染器提供一般在文檔中插入一個占位標(biāo)記渲染時自動掃描所有標(biāo)題生成目錄。這種方式適合平臺和工具支持能力強(qiáng)的場景改標(biāo)題后目錄會跟著更新幾乎不用維護(hù)。手動目錄是手寫的鏈接列表指向各標(biāo)題的錨點(diǎn)。Markdown 渲染 HTML 時標(biāo)題會自帶錨點(diǎn)鏈接到錨點(diǎn)的方法在 2.5 節(jié)提過[文字](#鏈接目標(biāo))。不過不同平臺對中文錨點(diǎn)的處理策略不同有的自動轉(zhuǎn)拼音有的保留中文有的忽略大小寫和空格。手寫錨點(diǎn)時最穩(wěn)的做法是先去預(yù)覽頁面里復(fù)制實(shí)際生成的錨點(diǎn)地址拿來直接用不要憑想象寫。我個人更傾向于自動生成目錄。原因很直白文檔經(jīng)常要改標(biāo)題手寫目錄表同步更新很容易遺漏而自動目錄不會出這種問題。維護(hù)成本低出錯率低長期看一定更劃算。4.4 配合版本管理沉淀資產(chǎn)最后想提一下版本管理。如果你寫的是項(xiàng)目文檔強(qiáng)烈建議把 Markdown 文檔目錄一起納入版本管理。這樣每次改動都有記錄時間久了可以回溯也可以對比不同版本之間內(nèi)容的變化。Markdown 是純文本差異對比非常清晰哪個詞被改了、哪一段被刪了都?xì)v歷在目。這個習(xí)慣在合作場景下價值更大。幾個人同時維護(hù)一份文檔版本合并的沖突提示非常直觀Markdown 不像二進(jìn)制文件那樣需要專業(yè)工具才能解析直接用文本對比工具就能解決大部分沖突。我講一個真實(shí)的體會曾經(jīng)有一次合作者改完文檔后不小心刪掉了一整節(jié)內(nèi)容但因?yàn)槲臋n在版本管理里幾分鐘就找回了舊版本避免了返工。5. 常見問題與排查技巧實(shí)錄很多人學(xué)完語法就開始寫但寫著寫著會遇到各種奇怪的現(xiàn)象感覺好像哪兒都不對。這一節(jié)我把實(shí)際使用里最常遇到的問題和排查思路整理成速查式的列表你遇到類似情況時可以直接對照。5.1 換行不生效這是被問得最多的問題。很多新手在 Markdown 里寫完一段后直接按一次回車渲染出來發(fā)現(xiàn)和上一段擠在一起。原因在于Markdown 中單個換行符在大多數(shù)平臺上會被當(dāng)作普通空格處理只有空一行才能表示段落換行。這是一個歷史遺留約定但今天幾乎所有主流渲染器都會這樣處理。解決辦法有三個段落之間空一行在行尾加兩個空格再換行或者直接使用 HTML 的br標(biāo)簽。我最推薦的是空一行它語義最清晰源碼也更整潔。行尾加空格是個隱藏技巧肉眼幾乎看不出來在編輯文檔時容易造成誤解。br適合不想分段、只想強(qiáng)制斷行的情況但盡量少用因?yàn)樗鼤茐募兾谋镜目勺x性。5.2 表格錯亂表格渲染異常十有八九是管道符數(shù)量不統(tǒng)一。當(dāng)你看到表格幾行單元格錯位、多出一列或者直接漏掉內(nèi)容時先逐行數(shù)管道符。管道符數(shù)量一致是對齊的底線。另一個坑是表頭分隔行缺失。沒有第二行| --- |渲染器就不會把后續(xù)內(nèi)容當(dāng)表格而是當(dāng)普通段落文字處理。有些新手以為只要用管道符分隔了內(nèi)容就能自動生成表格其實(shí)不對表頭分隔行才是觸發(fā)表格渲染的開關(guān)。5.3 列表里嵌代碼塊失效在列表項(xiàng)里放代碼塊縮進(jìn)層級是一個大坑。列表項(xiàng)后面的內(nèi)容要縮進(jìn)到和列表內(nèi)容相同的層級否則會被拍平成列表外的內(nèi)容。最典型的場景- 第一項(xiàng) python print(hello)這里的代碼塊前面直接縮進(jìn)兩個空格是配合列表項(xiàng)內(nèi)容對齊的。如果你把代碼塊頂格寫渲染時代碼塊會直接跳出列表位置錯亂。我的建議是遇到復(fù)雜列表內(nèi)嵌代碼的情況優(yōu)先考慮把代碼塊和列表拆開各自獨(dú)立成塊。形式上的嵌套好看但維護(hù)起來很容易出問題。文檔的第一要務(wù)是內(nèi)容清晰而不是源碼精美。 ### 5.4 圖片要么不變大要么不居中 圖片占不滿寬度、沒法居中是另一個高頻問題。原生 Markdown 圖片語法不提供尺寸和位置控制這在寫正式文檔時尤為頭疼。多數(shù)平臺的渲染器會保留圖片原始尺寸除非你在圖片地址后跟了尺寸設(shè)置但不同平臺的擴(kuò)展語法格式不一通用性很差。 我的做法是直接用 HTML 的 img 標(biāo)簽代替。雖然它帶一點(diǎn)樣式味道但幾乎所有接近完整的渲染引擎都支持。寫正式文檔時圖片寬度設(shè)置為 100% 是相當(dāng)常見的處理方式它能保證圖片在不同屏幕寬度下自適應(yīng)不會被原始分辨率限制。 另外要注意HTML 標(biāo)簽在 Markdown 里只寫一行前后不要有多余空行否則某些嚴(yán)格模式下的渲染器會把 HTML 標(biāo)簽單獨(dú)識別為段落塊導(dǎo)致布局出現(xiàn)意外空白。 ### 5.5 不同平臺顯示效果不一樣 同一個 Markdown 文件在編輯器和博客平臺上的渲染效果可能天差地別。原因在于并不存在一個官方權(quán)威的 Markdown 規(guī)范各家實(shí)現(xiàn)都是在一個共同子集上做擴(kuò)展。兼容性問題的根源在這里。 我的經(jīng)驗(yàn)是優(yōu)先寫“通用子集”語法也就是絕大多數(shù)渲染器都能正確解析的那部分。遇到漂亮的擴(kuò)展語法時先想清楚這份文檔只在當(dāng)前平臺看還是以后可能遷移如果要遷移擴(kuò)展語法能不用就不用。進(jìn)階用法在交付外部文檔時尤其要克制。 還有一個很實(shí)用的小技巧發(fā)布前在至少兩款不同的渲染器里預(yù)覽一遍。如果兩款都能正常渲染基本就不會出大問題。如果只有一款正常趕緊找出問題源頭的語法不要等到讀者反饋才發(fā)現(xiàn)。 ## 6. 用 Markdown 寫作的長期習(xí)慣 寫了這么久我對 Markdown 最深的體會是它沒有綁定任何一家公司的生態(tài)也沒有特定的軟件限制。它的形態(tài)極其簡單以至于幾乎不可能被淘汰。我剛接觸時覺得這不過是給技術(shù)人員準(zhǔn)備的排版工具后來慢慢發(fā)現(xiàn)它其實(shí)在改變寫作習(xí)慣本身——你開始把注意力放在結(jié)構(gòu)和內(nèi)容上而不是讓格式牽著鼻子走。 如果現(xiàn)在讓我給剛開始用 Markdown 的人提一個建議我不會推薦某款編輯器也不會上來就布置一堆高級語法任務(wù)而是建議從今天開始找一篇你最近要寫的文檔強(qiáng)迫自己用 Markdown 寫完整。第一次肯定會不習(xí)慣會頻繁查看語法會忘記空行會把表格寫散架。這些都是正常的寫兩三篇之后就會順暢起來。到那時候你再回頭看傳統(tǒng)排版工具會很自然地明白為什么這么多人離不開它。 至于進(jìn)階方向等你基礎(chǔ)牢固了可以試試模板化寫作、主題樣式定制、甚至自己寫一個小腳本批量轉(zhuǎn)換文檔。但這些都是后話。先把 # 和 * 這些最基礎(chǔ)的符號用順比什么技巧都重要。