更好、更快、更小Material for MkDocs 客户端搜索重构全解析【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material本文是 Material for MkDocs 对客户端搜索client-side search进行彻底重构的技术内幕剖析围绕搜索索引构造、lunr 分词、搜索预览生成与命中高亮四条主线展开。读完你将理解新版搜索为何在保留多语言、离线可用、纯客户端能力的同时把索引体积压缩近一半、搜索提速至原先的近 20 倍并能据此自定义separator分词规则、诊断搜索索引结构与预览效果。文中所有结论均与当前仓库的插件实现src/plugins/search/plugin.py和前端集成源码src/templates/assets/javascripts/integrations/search一一对应。背景为什么要重写搜索在 Material for MkDocs 中搜索是用户最依赖的能力之一它支持多语言分词、离线使用并且完全在客户端运行——索引由构建期生成的内置搜索插件产出用户访问页面时在浏览器内完成检索无需额外维护搜索服务器。尽管旧版搜索已经过多轮迭代仍存在三个结构性问题索引冗余导致体积偏大、纯文本索引丢失文档结构、预览与高亮对中日文等非空白分隔语言支持不佳。下面先拆解旧实现的架构再逐一说明重构方案如何解决这些痛点。旧架构剖析Material for MkDocs 的客户端搜索基于 lunr 及 lunr-languages 实现。页面加载并启用 JavaScript 后前端会向服务器请求构建期生成的搜索索引const index$ document.forms.namedItem(search) ? __search?.index || requestJSONSearchIndex( new URL(search/search_index.json, config.base) ) : NEVER旧版搜索索引内容重复且结构尽失搜索索引收录所有页面的精简版本。以如下 Markdown 页面为例# Example ## Text Its very easy to make some words **bold** and other words *italic* with Markdown. You can even add [links](#), or even code: if (isAwesome) { return true } ## Lists Sometimes you want numbered lists: 1. One 2. Two 3. Three Sometimes you want bullet points: * Start a line with a star * Profit!构建期产出的旧版search_index.json如下{ config: { indexing: full, lang: [ en ], min_search_length: 3, prebuild_index: false, separator: [\\s\\-] }, docs: [ { location: page/, title: Example, text: Example Text Its very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true } Lists Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit! }, { location: page/#example, title: Example, text: }, { location: page/#text, title: Text, text: Its very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true } }, { location: page/#lists, title: Lists, text: Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit! } ] }对照源码可以立即发现两个明显问题所有内容被索引了两遍索引中既有整页内容的完整条目又有按标题切分的每个章节条目直接推高了索引体积。当前仓库的SearchIndex.create_entry_for_section见 src/plugins/search/plugin.py通过 HTML 解析器按 h1–h6 标题将页面切成Section再生成location/title/text条目旧版索引的双份条目正是这种整页 章节结构造成的。所有结构信息全部丢失构造索引时 HTML 标签和属性被剥除段落与行内格式尚可接受但列表和代码块会变得难以阅读… links , or even code : if (isAwesome) { … } Lists Sometimes you want …由此产生两类次生问题上下文缺失读者难以分辨哪部分是正文、哪部分是代码Lists作为标题也被与前文代码块、后文段落糊成一团标点错位紧随链接等行内元素之后的标点被空白分隔如上例中的,和:因为所有提取文本在拼装索引时都以空格拼接。正是因为这种纯文本索引很难生成有意义的预览旧版 Material for MkDocs 不得不对 lunr 做 monkey patching 来拼凑稍可读的搜索摘要。如今这一切都已被新实现取代。搜索 worker 的三步流水线实际的检索逻辑运行在 Web Worker 中入口见 src/templates/assets/javascripts/workers/search.ts消息处理在 src/templates/assets/javascripts/integrations/search/worker/main/index.ts。Worker 负责创建并管理 lunr 索引初始化时分三步章节与页面建立关联解析搜索索引将每个章节绑定到其所属页面。父页面本身不参与索引否则会产生重复结果建立关联是为了最终按页面分组展示结果。对应前端实现为setupSearchDocumentMapsrc/templates/assets/javascripts/integrations/search/config/index.ts它依赖文章条目先于其全部章节条目的索引顺序约定将带锚点的条目挂到父文章下。分词Tokenization按mkdocs.yml中配置的separator将每个章节的title与text切分为 token。旧版使用 lunr 的默认分词器它不支持前瞻lookahead也无法处理跨多字符的分隔符——这正是下文分词器前瞻一节的关键伏笔。索引Indexing为每个章节建立索引。查询时命中第 2 步产出的任一 token 的章节即进入结果集交给主线程渲染。除此之外还有一些细节处理例如结果会被后处理并按相关性重打分以弥补 lunr 的部分短板。从当前仓库的Search.searchsrc/templates/assets/javascripts/integrations/search/_/index.ts可以看到完整的后处理链路解析查询子句 → lunr 检索 → 按字段高亮命中位置 → 按标题命中数与词项命中率施加后查询加权score * (1 boost ** 2)→ 重新排序 → 按文章分组并补全空命中条目。说明在 Material for MkDocs 5.0.0 之前搜索在主线程执行会阻塞浏览器渲染该问题由 issue #904 报告并在 5.0.0 版本中修复从此检索完全移入 Web Worker。搜索预览的缺陷320 字符截断用户需要在上下文里快速判断某条结果的关联度因此摘要 命中词高亮是搜索体验的关键。旧版预览的一个突出问题是部分预览根本不包含任何搜索词原因是预览在最多 320 字符处截断上图前两条结果看起来与查询无关但它们确实是命中的——只是截断点刚好落在命中词之前。要彻底解决这个问题需要同时考虑三个因素词边界Word boundaries部分静态站点生成器的主题采用命中词左右按空白扩展开、凑足单词数即停的预览策略例如… channels, e.g., or which can be configured via mkdocs.yml …。这对以空白分隔词的语言可行但对日语、汉语等没有空白边界的语言完全失效——这些语言依赖专门的分词器来切分字符串。当时 Just the Docs 与 Docusaurus 采用的就是这种按空白扩展的方式而 Material for MkDocs 的中国与日本用户量均居全球前五非空白分隔语言的支持绝非边缘需求。上下文感知Context-awareness即便空白扩展能凑合对代码块也未必成立——某些语言移除空白会改变语义预览时应当保留代码块的原始形态。结构Structure保留结构信息并非必需但显然有助于生成可快速评估相关度的预览——若命中词出现在代码块中预览就应以代码块形式渲染。新特性总览围绕上述问题重构后的搜索带来两类收益更好Better支持富搜索预览保留代码块、行内代码与有序/无序列表的结构信息并按原样渲染引入分词器前瞻、更精确的高亮、更稳定的输入联想typeahead以及若干界面细节优化。更快、更小Faster Smaller通过改进的提取与索引构造技术搜索索引体积最多减少 48%整体搜索体验最多提速 95%对大型文档项目尤为显著。富搜索预览Rich search previews由于搜索插件被完全重写索引构造也重新设计代码块、行内代码以及无序/有序列表的结构信息得以保留。还是上文那个例子效果对比重构后Now代码块成为搜索预览的一等公民行内代码格式也被保留。重构前Before所有结构被拍平为连续文本。新索引结构让这一切成为可能。对比新旧两份search_index.json Now json { ... docs: [ { location: page/, title: Example, text: }, { location: page/#text, title: Text, text: pIts very easy to make some words bold and other words italic with Markdown. You can even add links, or even codecode/code:/p precodeif (isAwesome){\n return true\n}\n/code/pre }, { location: page/#lists, title: Lists, text: pSometimes you want numbered lists:/p ol liOne/li liTwo/li liThree/li /ol pSometimes you want bullet points:/p ul liStart a line with a star/li liProfit!/li /ul } ] } Before json { ... docs: [ { location: page/, title: Example, text: Example Text Its very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true } Lists Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit! }, { location: page/#example, title: Example, text: }, { location: page/#text, title: Text, text: Its very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true } }, { location: page/#lists, title: Lists, text: Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit! } ] } 改进体现在两点内容只收录一次索引不再同时保存整页与章节两份文本只保留各章节条目体积显著下降、传输字节更少。保留部分结构每个章节条目内嵌一小撮 HTML为生成更精致的预览提供结构支撑 Now html … links, or even codecode/code:/p precodeif (isAwesome){ … }\n/code/pre Before … links , or even code : if (isAwesome) { … } 标点错位问题消失不再额外插入空白保留的标记则让扫描结果时上下文一目了然。从源码看这套能力由插件侧重写的Parsersrc/plugins/search/plugin.py支撑它维护两组标签集合——需要整体跳过的skip如script、style、object与需要保留的keepp、code、pre、li、ol、ul、sub、sup并在handle_starttag/handle_endtag/handle_data中把保留标签的原样 HTML 与转义后的文本追加进章节的title/text。此外data-search-exclude属性与代码行号容器linenodiv也会被显式跳过避免把不该索引的内容混入。前端侧对应的提取器extractsrc/templates/assets/javascripts/integrations/search/internal/extract/index.ts随后把文本流按开标签 / 文本 / 闭标签三类切块供分词与位置记录使用。分词器前瞻Tokenizer lookaheadlunr 的默认分词器用正则把字符串按separator逐字符匹配切分无法表达基于前瞻或跨多字符的复杂分隔符。新搜索实现提供了更强大的分词器从源码注释看它明确取代 lunr 提供的默认分词器因为它能感知 HTML 标签并支持多字符切分src/templates/assets/javascripts/integrations/search/internal/tokenize/index.ts。正因如此Material for MkDocs 把自己的separator配置改成了下面这个值[\s\-,:!\[\]()/]|(?!\b)(?[A-Z][a-z])|\.(?!\d)|[lg]t;竖线分隔的四段各司其职第一段是常见控制字符集合切分点即分隔符后三段则利用前瞻解决了三个经典难题。顺带一提搜索插件separator的默认值[\s\-]一直容易让人误以为支持多字符分隔符但 lunr 默认分词器从来就不支持涉及多字符的正则分组实际上毫无意义。新分词器才是让这类复杂表达式真正生效的关键。在mkdocs.yml中可通过plugins.search.separator配置该值对应配置项定义见 src/plugins/search/config.py完整说明见 搜索插件配置文档plugins: - search: separator: [\s\-,:!\[\]()/]|(?!\b)(?[A-Z][a-z])|\.(?!\d)|[lg]t;大小写变化Case changes多数编程语言采用PascalCase或camelCase命名。用户搜索case时理应能命中PascalCase与camelCase。下面这组匹配项实现了这一点(?!\b)(?[A-Z][a-z])它是负向前瞻非词边界\b与正向前瞻大写字母后跟小写字母[A-Z][a-z]的组合行为如下PascalCase→Pascal、CasecamelCase→camel、CaseUPPERCASE→UPPERCASE不切分因此搜索searchHighlight能正确命中讨论search.highlight功能开关的章节——这在旧版是做不到的旧版为输入联想typeahead会给每个搜索词追加通配符而 lunr 对含通配符的查询会禁用 pipeline导致查询本身也无法被正确分词。版本号Version numbers版本号索引是另一个可用前瞻解决的老问题。通常.应作为分隔符切分search.highlight这类词但若在版本号处也切分7.2.6这样的版本将不可检索。于是\.(?!\d)该表达式只在.后面不是数字时才作为分隔符版本号得以保持完整可检索——例如搜索7.2.6能直接定位到对应的更新日志。HTML/XML 标签若文档包含 HTML/XML 代码示例用户可能希望直接检索标签名。问题在于代码块中的与会被转义为lt;与gt;。加入下面这组表达式即可解决[lg]t;配合上文的控制字符集合、、lt;、gt;都会被当作分隔符处理标签名因此可以独立成词被索引。精确高亮Accurate highlighting高亮是搜索流程的最后一环为结果中的所有命中词着色。旧实现长期依赖动态生成的正则表达式——用mkdocs.yml中定义的separator拼出一个试图模拟分词器的正则例如把查询search highlight变成(^|separator)(search|highlight)只能匹配词边界上的命中。这种方式对日语、汉语等非空白分隔语言存在先天缺陷这些语言由专门的分词器segmenter切分无法用正则建模。而新实现直接受益于新的分词方案——用 token 位置做高亮能力上限与分词完全对齐。前端的位置表驱动高亮实现在 src/templates/assets/javascripts/integrations/search/internal/highlight/index.ts索引期分词器把每个 token 的块号 块内序号编码进position见 src/templates/assets/javascripts/integrations/search/internal/tokenize/index.ts查询期Search.search收集命中位置后按块切出slice并以mark包裹命中片段。位置驱动高亮带来两点关键改进词边界 token 边界凡是分词能覆盖的复杂场景——大小写变化、版本号、HTML/XML 标签——高亮都能精确命中不再依赖词边界的正则近似。上下文感知的内容块新索引保留部分结构信息后章节内容被划分为段落、代码块、列表等独立内容块。只有实际包含命中词的内容块才会进入搜索预览若命中只出现在代码块里预览渲染的就是代码块本身——例如搜索twitter时只会看到包含该词的代码片段。基准测试Benchmarks团队做了两组基准一组使用 Material for MkDocs 自身的文档另一组使用超过80 万词的超大语料绝大多数文档项目都不会达到这个量级BeforeNowRelativeMaterial for MkDocsIndex size573 kB335 kB–42%Index size (gzip)105 kB78 kB–27%Indexing time265 ms177 ms–34%KJV MarkdownIndex size8.2 MB4.4 MB–47%Index size (gzip)2.3 MB1.2 MB–48%Indexing time2,700 ms1,390 ms–48%Indexing time 取十次独立运行的最小值超大语料测试使用 KJV Markdown 语料——一组超过 80 万词的 Markdown 文件集合用来观察项目在大型语料上的表现。结果表明索引建立时间最多下降 48%而索引建立时间直接决定页面加载后搜索就绪的耗时因此新搜索整体最多提速 95%——这对大型文档项目意义重大。1.3 秒听上去仍然不短但如果配合即时加载instant loading使用索引只在首次页面加载时构建一次页面间导航时索引跨页保留这份成本只需支付一次。从构建侧看当前仓库还针对增量构建做了专门优化——SearchPlugin在 dirty reload 模式下持久化上一次的索引search_index_prev并在generate_search_index中只更新当前页面所属条目避免整站重建src/plugins/search/plugin.py。用户界面改进此外还有一些小的交互优化最明显的是本页更多结果more results on this page按钮——当结果列表打开时它会吸顶固定让用户能更快地从长列表中跳出。未来展望新搜索解决了一些存在多年的老大难问题但这只是更好搜索体验的开端接下来有两个明确方向上下文感知的摘要生成目前预览取前两个命中的内容块渲染。新的分词技术已为更精细的缩短与摘要方法打好地基。用户界面增强完全掌控搜索插件后可以给结果附加有意义的元数据提供更多上下文和更优体验。此外分词器前瞻的价值远不止本文列出的表达式——如果你发现了其他实用的separator组合值得在文档社区分享。当前仓库的完整实现插件侧 src/plugins/search/plugin.py、配置模型前端侧 分词器、提取器、高亮器、Worker 主逻辑与官方搜索配置指南、站点搜索设置指南一起构成了理解并调优这套客户端搜索的完整素材。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考