文檔靜態(tài)站點(diǎn)UI組件【免費(fèi)下載鏈接】just-the-docsA modern, high customizable, responsive Jekyll theme for documentation with built-in search.項(xiàng)目地址https://gitcode.com/gh_mirrors/ju/just-the-docs點(diǎn)擊查看免費(fèi)下載本指南以 Just the Docs 主題中帶行號(hào)代碼塊Code Snippets with Line Numbers為核心剖析 Jekyll 高亮代碼生成無(wú)效 HTML 的根因并給出compress_html與kramdown的標(biāo)準(zhǔn)配置方法、Liquid 標(biāo)簽局部抑制技巧以及為什么舊的fix_linenos修復(fù)方案已被官方棄用。讀完本文你將能在自己的 Just the Docs 站點(diǎn)上安全地啟用行號(hào)、避免頁(yè)面布局錯(cuò)亂并理解底層 HTML 結(jié)構(gòu)為什么會(huì)出錯(cuò)。問(wèn)題背景語(yǔ)法高亮、行號(hào)與 HTML 壓縮三者不能共存Just the Docs 是一個(gè)基于 Jekyll 的現(xiàn)代文檔主題代碼高亮由 Jekyll 內(nèi)置的 Rouge 高亮器完成。開(kāi)發(fā)者通常希望代碼塊既帶語(yǔ)法高亮、又帶行號(hào)同時(shí)開(kāi)啟 HTML 壓縮以減小頁(yè)面體積。但文檔明確警告這三者同時(shí)啟用會(huì)產(chǎn)生無(wú)效 HTML導(dǎo)致渲染異?！獰o(wú)論是使用 Kramdown 代碼圍欄code fences還是 Liquid 的highlight標(biāo)簽Jekyll 生成的帶行號(hào) HTML 都與 HTML 壓縮的默認(rèn)設(shè)置不兼容。這一結(jié)論并非本頁(yè)獨(dú)有UI 組件總覽中同樣以一句話點(diǎn)明了核心約束“Syntax highlighting, line numbers, and HTML compression do not work together; the combination of these features generates invalid HTML that renders incorrectly.”從倉(cāng)庫(kù)當(dāng)前的 _config.yml 可以看到官方站點(diǎn)的默認(rèn)取值kramdown: syntax_highlighter_opts: block: line_numbers: false compress_html: clippings: all comments: all endings: all startings: [] blanklines: false profile: false # ignore: # envs: all即官方默認(rèn)關(guān)閉行號(hào)line_numbers: false且 HTML 壓縮的ignore/envs處于注釋狀態(tài)。如果你在生成環(huán)境中觀察到了代碼塊布局異常多半就是在這兩項(xiàng)配置上開(kāi)了“口子”。官方推薦配置兩段 YAML 解決問(wèn)題關(guān)閉 HTML 壓縮對(duì)高亮代碼的處理要避免不合規(guī)范的 HTML 與糟糕的布局最簡(jiǎn)單且官方推薦的方案是讓 HTML 壓縮完全忽略高亮代碼塊的輸出compress_html: ignore: envs: all把這段配置加入站點(diǎn)的_config.yml后Jekyll 在生成頁(yè)面時(shí)將跳過(guò)對(duì)代碼塊的壓縮處理保留 Rouge 原始輸出的結(jié)構(gòu)完整性。用 Kramdown 配置全局開(kāi)啟行號(hào)如果希望站點(diǎn)內(nèi)所有代碼圍欄lang形式都顯示行號(hào)可以在_config.yml中設(shè)置kramdown: syntax_highlighter_opts: block: line_numbers: true局部抑制行號(hào)改用 Liquid 標(biāo)簽代替圍欄全局開(kāi)啟行號(hào)后若個(gè)別代碼塊不希望顯示行號(hào)不要試圖通過(guò)圍欄的某種局部語(yǔ)法關(guān)閉它。官方給出的做法是改用 Liquid 的highlight標(biāo)簽不帶linenos選項(xiàng)來(lái)包住這段代碼{% highlight some_language %} Some code {% endhighlight %}由于 Liquidhighlight標(biāo)簽?zāi)J(rèn)不輸出行號(hào)用它包裹的代碼塊自然不受全局line_numbers: true影響從而實(shí)現(xiàn)了“全局默認(rèn)帶行號(hào)、局部個(gè)別不帶”的靈活控制。反過(guò)來(lái)如果全局關(guān)閉行號(hào)又可以在單個(gè)代碼塊上用帶linenos選項(xiàng)的 Liquid 標(biāo)簽單獨(dú)開(kāi)啟行號(hào)Changelog 中記錄了該能力CHANGELOG.md “Support for the linenos option on highlighted code”。詳細(xì)錯(cuò)誤解析為什么生成的 HTML 是無(wú)效的下面是一個(gè)試圖高亮簡(jiǎn)單 Ruby 程序的代碼塊使用了linenos選項(xiàng){% highlight ruby linenos %} def foo puts foo end {% endhighlight %}當(dāng)它被 Jekyll經(jīng) Just the Docs、并開(kāi)啟 HTML 壓縮處理后會(huì)生成如下標(biāo)記figure classhighlightcode classlanguage-ruby>figure classhighlight code classlanguage-ruby>贊分享文檔靜態(tài)站點(diǎn)UI組件【免費(fèi)下載鏈接】just-the-docsA modern, high customizable, responsive Jekyll theme for documentation with built-in search.項(xiàng)目地址https://gitcode.com/gh_mirrors/ju/just-the-docs點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Just the Docs 項(xiàng)目配置詳解Just the Docs 項(xiàng)目配置詳解 前言 Just the Docs 是一個(gè)基于 Jekyll 的現(xiàn)代化文檔主題專(zhuān)為技術(shù)文檔設(shè)計(jì)。它提供了簡(jiǎn)潔的界面和強(qiáng)文檔靜態(tài)站點(diǎn)UI組件三步掌握Memos標(biāo)簽管理層級(jí)標(biāo)簽、樹(shù)形篩選與批量重命名三步掌握Memos標(biāo)簽管理層級(jí)標(biāo)簽、樹(shù)形篩選與批量重命名 Memos 是一款開(kāi)源、可自托管的輕快記筆記工具原生基于 Markdown。它的標(biāo)簽體系沒(méi)有獨(dú)立的后端前端知識(shí)管理終極指南如何用welle.io打造專(zhuān)業(yè)級(jí)DAB/DAB數(shù)字廣播接收系統(tǒng)終極指南如何用welle.io打造專(zhuān)業(yè)級(jí)DAB/DAB數(shù)字廣播接收系統(tǒng) welle.io 是一款功能強(qiáng)大的開(kāi)源軟件定義無(wú)線電SDR接收器專(zhuān)為DAB/D上一篇3步部署智能對(duì)比測(cè)試平臺(tái)Diffy實(shí)戰(zhàn)指南下一篇MiniMind 本地部署26M 輕量模型跑通命令行對(duì)話與 WebUI創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考