Prettier Markdown 腳注定義格式化全解析長段落折行、proseWrap 策略與源碼實現(xiàn)【免費下載鏈接】prettierPrettier is an opinionated code formatter.項目地址: https://gitcode.com/gh_mirrors/pr/prettier本文以 Prettier 倉庫中的腳注定義格式化測試夾具tests/format/markdown/footnoteDefinition/long.md為核心深入剖析 Prettier 如何處理 Markdown 腳注定義footnote definition中的超長段落。讀完本文你將掌握proseWrap三種取值對腳注折行的實際影響、腳注內(nèi)容固定 4 空格縮進的底層原理以及如何通過源碼與快照測試驗證這些格式化行為。一、腳注定義語法與測試夾具定位Markdown 腳注footnote由兩部分組成正文中的腳注引用[^label]與文末的腳注定義[^label]: content。Prettier 在格式化 Markdown 時會對腳注定義進行專門的排版處理。倉庫中與之對應的測試目錄是 tests/format/markdown/footnoteDefinition包含四個輸入夾具與配套快照文件覆蓋場景l(fā)ong.md超長段落腳注定義含續(xù)行simple.md最短的單行腳注定義multiline.md包含代碼塊、引用塊的腳注定義sibling.md大量相鄰腳注定義與多行引用內(nèi)容這些夾具由 format.test.js 驅(qū)動分別以proseWrap: always、proseWrap: never、proseWrap: preserve和tabWidth: 3四組選項運行格式化輸出結(jié)果全部記錄在 format.test.js.snap 快照中。該測試通過倉庫統(tǒng)一的格式測試基架見 format-test-setup.js執(zhí)行。二、long.md 場景還原三種 proseWrap 模式的行為對比long.md的輸入極其簡短僅三行但覆蓋了兩個典型形態(tài)[^hello]: this is a long long long long long long long long long long long long long paragraph. [^world]: this is a long long long long long long long long long long long long long paragraph. this is a long long long long long long long long long long long long long paragraph.其中[^hello]是單行定義[^world]的第三行是前一行段落的續(xù)行Markdown 語法中同一段落可以跨多行源碼因此[^world]是一個跨兩行的段落。這兩種形態(tài)恰好觸發(fā)了 Prettier 不同的格式化分支。1.proseWrap: always一律塊級排版并按 80 列折行快照中l(wèi)ong.md - {proseWrap:always}的輸出為[^hello]: this is a long long long long long long long long long long long long long paragraph. [^world]: this is a long long long long long long long long long long long long long paragraph. this is a long long long long long long long long long long long long long paragraph.關(guān)鍵行為標簽與內(nèi)容分行兩個腳注的[^label]:都單獨成行正文縮進 4 個空格。按 printWidth默認 80折行正文在超過 80 列時自動換行續(xù)行同樣縮進 4 個空格。續(xù)行并入同一段落[^world]的續(xù)行與首行合并為同一個段落后統(tǒng)一重排不再保留源碼的換行位置。2.proseWrap: never全部內(nèi)聯(lián)為單行[^hello]: this is a long long long long long long long long long long long long long paragraph. [^world]: this is a long long long long long long long long long long long long long paragraph. this is a long long long long long long long long long long long long long paragraph.此時無論內(nèi)容多長都不折行定義內(nèi)容緊跟[^label]:后內(nèi)聯(lián)輸出[^world]的續(xù)行也被合并為一行完全忽略 printWidth 限制。3.proseWrap: preserve保留源碼的換行形態(tài)[^hello]: this is a long long long long long long long long long long long long long paragraph. [^world]: this is a long long long long long long long long long long long long long paragraph. this is a long long long long long long long long long long long long long paragraph.[^hello]在源碼中是單行輸出保持內(nèi)聯(lián)單行[^world]在源碼中跨兩行輸出轉(zhuǎn)為塊級形態(tài)標簽單獨一行、正文按源碼原有的行邊界逐行保留僅統(tǒng)一縮進 4 個空格不按 80 列重新折行。行為對照表proseWrap單行定義跨行定義是否按 80 列折行標簽位置always塊級標簽換行塊級段落合并重排是獨立一行never內(nèi)聯(lián)單行內(nèi)聯(lián)單行段落合并否與內(nèi)容同行preserve內(nèi)聯(lián)單行塊級保留原行邊界否視源碼形態(tài)而定三、源碼級原理footnoteDefinition 的打印邏輯上述行為并非黑盒魔法其實現(xiàn)位于 src/language-markdown/print/mdast.js 的footnoteDefinition分支case footnoteDefinition: { const shouldInlineFootnote node.children.length 1 node.children[0].type paragraph (options.proseWrap never || (options.proseWrap preserve node.children[0].position.start.line node.children[0].position.end.line)); return [ printFootnoteReference(node), : , shouldInlineFootnote ? printChildren(path, options, print) : group([ align( .repeat(4), printChildren(path, options, print, { processor: ({ isFirst }) isFirst ? group([softline, print()]) : print(), }), ), ]), ]; }逐一拆解1. 內(nèi)聯(lián)判定的三重條件shouldInlineFootnote腳注定義只有在同時滿足以下條件時才以內(nèi)聯(lián)形態(tài)輸出定義體只有一個子節(jié)點且類型是paragraph即純段落不含代碼塊、引用塊等proseWrap never或proseWrap preserve且該段落在源碼中起始行號與結(jié)束行號相同單行。這解釋了long.md中的現(xiàn)象always模式下永遠走塊級分支never模式下只要體是單段落就內(nèi)聯(lián)preserve模式下單行定義內(nèi)聯(lián)、跨行定義轉(zhuǎn)為塊級。2. 固定 4 空格縮進align( .repeat(4), ...)塊級分支通過align將子節(jié)點整體縮進 4 個空格——這是硬編碼的不隨tabWidth變化。這正是快照中tabWidth: 3的用例輸出與preserve完全一致、縮進仍為 4 空格的原因。3. 首行軟換行g(shù)roup([softline, ...])塊級分支對第一個子節(jié)點前置softline并包在group中若整體寬度放得下則softline折疊為空格標簽與內(nèi)容同行如multiline.md中較短的腳注放不下則斷行標簽單獨成行如long.md中的always輸出。4. 段落折行引擎fill塊級正文的按寬度折行由 src/language-markdown/print/sentence.js 中的printSentence實現(xiàn)——它遍歷段落的單詞與空白節(jié)點用fill(parts)組裝文檔fill在超出 printWidth 時自動插入換行。因此always模式下的腳注正文與普通段落享受同一套折行機制。四、相鄰定義與多行內(nèi)容的格式化細節(jié)sibling.md與multiline.md補充了更復雜的場景相鄰定義強制用空行分隔無論哪種proseWrap模式連續(xù)出現(xiàn)的多個腳注定義在輸出中都會被空行隔開避免定義塊粘連見 sibling.md 的快照輸出。多行引用塊[^a]: 123\與續(xù)行 456這類多行 blockquote 在塊級分支下引用內(nèi)容整體縮進 4 空格[^a]: 123\ 456含代碼塊的腳注體當定義體不是單一段落例如段落加代碼塊時shouldInlineFootnote恒為false即使proseWrap: never也會走塊級分支。此時短段落仍可與標簽同行g(shù)roup 不斷行而長段落會迫使 group 斷行、標簽獨立成行代碼塊內(nèi)容按 Markdown 語法保持 4 空格縮進。完整輸入輸出可對照 multiline.md 與對應快照。五、proseWrap 選項定義、默認值與配置方式proseWrap是影響腳注排版的核心開關(guān)在 src/common/common-options.evaluate.js 中定義屬性值類型choice枚舉默認值preserve可選值always超寬即折行、never不折行、preserve保持原樣它是 Prettier 的通用選項Markdown 語言插件在 src/language-markdown/options.js 中直接復用可通過配置文件或 CLI 指定// prettier.config.js export default { proseWrap: always, // 或 never / preserve };prettier --prose-wrap always README.md官方選項說明可進一步查閱 docs/options.md。需要留意proseWrap只影響段落類內(nèi)容含腳注定義正文的折行不影響代碼塊、表格等非散文內(nèi)容。六、如何復現(xiàn)與驗證若想在本地復現(xiàn)long.md的全部格式化行為可直接對夾具運行 Prettiernpx prettier --parser markdown --prose-wrap always tests/format/markdown/footnoteDefinition/long.md npx prettier --parser markdown --prose-wrap never tests/format/markdown/footnoteDefinition/long.md npx prettier --parser markdown --prose-wrap preserve tests/format/markdown/footnoteDefinition/long.md npx prettier --parser markdown --tab-width 3 tests/format/markdown/footnoteDefinition/long.md四組命令的輸出應與 format.test.js.snap 中l(wèi)ong.md的四個用例一一對應。該夾具由 format.test.js 通過runFormatTest執(zhí)行屬于倉庫統(tǒng)一的格式測試體系任何對 mdast.js 中腳注打印邏輯的改動都需要讓這組快照保持通過從而保證了腳注格式化行為的長期穩(wěn)定?？偨Y(jié)從三行測試輸入到完整的格式化語義long.md這一個夾具便覆蓋了 Prettier Markdown 腳注定義格式化的核心規(guī)則proseWrap決定內(nèi)聯(lián)還是塊級、是否折行純段落且滿足行數(shù)條件才可內(nèi)聯(lián)塊級內(nèi)容固定縮進 4 空格且不隨tabWidth變化折行復用fill段落引擎。理解 mdast.js 中shouldInlineFootnote的判定與align/softline/group的組合方式你就能準確預測任意腳注定義在 Prettier 下的輸出形態(tài)。【免費下載鏈接】prettierPrettier is an opinionated code formatter.項目地址: https://gitcode.com/gh_mirrors/pr/prettier創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考