Material for MkDocs 内置搜索插件search完全指南配置、分词与源码级原理【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-materialMaterial for MkDocs 自带的search插件无需安装任何外部服务即可为站点头部添加全文搜索栏并在构建阶段把生成的 HTML 解析成精简的搜索索引最终交给浏览器端的 lunr.js 完成索引与检索。本文将基于仓库中的 内置搜索插件文档 展开逐一讲解其工作原理、全部配置项lang、separator、pipeline、jieba_dict等、Front Matter 元数据search.boost、search.exclude并结合 搜索插件源码 与客户端 Search 类实现 剖析其底层机制帮你既能把搜索配到「开箱即用」也能针对多语言、中文分词与索引体积做精细化调优。插件目标轻量、离线可用的全文搜索工作原理search插件会在站点构建时扫描生成的 HTML从所有页面及其章节section中提取标题与正文内容构建一份搜索索引。索引构建会保留少量内联格式如代码块、列表其余全部格式被剥离从而让search_index.json的体积尽可能小——这正是它能在浏览器端全量加载的关键。用户访问站点时搜索索引随页面一同下发到浏览器由 [lunr.js] 在客户端完成索引与查询整个过程不需要任何服务端。也正因为索引是在构建期生成的它与文档内容永远保持一致搜索结果始终准确。[lunr.js]: 由 lunr.js轻量级浏览器端全文搜索引擎提供支持从源码看索引的构建与写盘由 SearchPlugin 完成on_page_context在每页渲染完成后调用add_entry_from_context把页面加入内存索引同时通过正则移除页面中的data-search-*属性标记on_post_build构建结束后把索引序列化为 JSON写入{site_dir}/search/search_index.json并对mkdocs serve --dirtyreload场景做了增量合并处理复用上一次构建的索引缓存。何时使用交互式搜索是优秀文档不可或缺的组成部分因此官方推荐默认启用该插件。此外它与其他 内置插件 协同良好离线插件offlineoffline 插件 支持构建离线可用文档可将site目录打包成可下载的.zip分发search插件因完全在浏览器端工作天然适配这种无网络也能搜索的使用场景。meta 插件meta 插件 允许通过 boost 提升特定章节的搜索相关性或用 exclude 将某些页面完全排除出索引实现对搜索更细粒度的控制。快速开始一行配置启用搜索search插件随 Material for MkDocs 内置发布无需单独安装。只需在mkdocs.yml中加入plugins: - searchenabled开关插件enabled设置默认true用于控制插件在 构建项目 时是否启用。通常无需显式指定但如果你想临时关闭插件可以这样写plugins: - search: enabled: false源码中 on_config 的第一步就是检查self.config.enabled为false时直接跳过所有初始化逻辑可见该开关作用于整个插件生命周期。搜索语言与中文分词lang / jiebalang指定索引语言lang设置默认自动计算用于指定搜索索引的语言为英语之外的语言启用词干提取stemming支持。默认值会根据 站点语言 自动计算也可以显式指定为其他语言甚至同时指定多种语言 单语言 yaml plugins: - search: lang: en 多语言 yaml plugins: - search: lang: # (1)! - en - de 注意每多支持一种语言基础 JavaScript 负载会增加约 20kb且每种语言额外增加 15-30kb均为 gzip 前体积。语言支持由社区维护的 lunr-languages 语言包提供包含各语言的词干提取器与停用词表。目前支持以下语言ar– 阿拉伯语da– 丹麦语de– 德语du– 荷兰语en– 英语es– 西班牙语fi– 芬兰语fr– 法语hi– 印地语hu– 匈牙利语hy– 亚美尼亚语it– 意大利语ja– 日语kn– 卡纳达语ko– 韩语no– 挪威语pt– 葡萄牙语ro– 罗马尼亚语ru– 俄语sa– 梵语sv– 瑞典语ta– 泰米尔语te– 泰卢固语th– 泰语tr– 土耳其语vi– 越南语zh– 中文若 lunr-languages 未提供所选 站点语言 的支持插件会自动回退到词干提取效果最佳的相近语言。在客户端语言包的加载由 search worker 脚本 完成构建期会针对每种语言动态importScripts对应的lunr.{lang}.min.js日语ja额外加载tinyseg.js分词器印地语hi与泰语th则加载wordcut.js当配置了多种语言时还会加载lunr.multi.min.js以启用多语言索引。中文分词jieba 与自定义词典search插件通过jieba流行的中文分词库在构建期对中文文本进行分词处理而日语、韩语等语言目前仍在客户端完成分词。相关设置如下jieba_dict替换默认词典jieba_dict实验性默认无用于指定 jieba 分词使用的自定义词典以替换其默认词典。jieba 自带多个词典可直接使用plugins: - search: jieba_dict: dict.txtjieba 提供的词典包括dict.txt.small– 占用内存较小的词典文件dict.txt.big– 支持繁体分词更好的词典文件路径相对于仓库项目根目录解析。jieba_dict_user附加用户词典jieba_dict_user实验性默认无用于指定附加的用户词典在默认词典之上进行增补非常适合微调分词效果plugins: - search: jieba_dict_user: user_dict.txt路径同样相对于项目根目录解析。插件源码 展示了这两项配置的实际处理逻辑jieba_dict通过jieba.set_dictionary(path)替换默认词典jieba_dict_user通过jieba.load_userdict(path)追加用户词两者都会先检查文件是否存在os.path.isfile不存在时输出 warning 日志而不是直接崩溃。分词的具体落点在于 SearchIndex._segment_chinese构建索引时用正则匹配所有Han脚本汉字片段交给jieba.cut切分并以零宽空白符\u200b包裹切分结果既保证了索引的可检索性又让切分后的词在渲染时「看起来」仍是连续文本。也就是说只要安装了 jieba中文文档在构建期就会被自动分词这是中文站点获得良好搜索结果的前提。separator精确控制分词边界separator设置默认自动计算用于指定客户端构建搜索索引时的分词分隔符。默认值根据 站点语言 自动计算也可以显式覆盖plugins: - search: separator: [\s\-,:!\[\]()/]|(?!\b)(?[A-Z][a-z])|\.(?!\d)|[lg]t;分隔符支持正向与负向先行断言因此可以写出相当复杂的表达式精确控制词语的切分方式。逐段拆解上面的默认表达式 特殊字符 [\s\-,:!\[\]()/] 表达式第一部分会在空白、连字符、逗号、方括号等特殊字符前后插入词边界多个相邻的特殊字符会被视为一个整体。 大小写变化 (?!\b)(?[A-Z][a-z]) 许多编程语言存在 PascalCase、camelCase 等命名约定。加入这个子表达式后分词会在大小写切换处断开例如把 PascalCase 切成 Pascal 和 Case让驼峰命名可被搜索。 版本号 \.(?!\d) 如果把 . 直接加入分隔符1.2.3 这类版本号会被切成 1、2、3从而无法通过搜索定位。该子表达式引入了一个负向先行断言遇到点号后跟数字时不切分从而**保留版本号字符串**、使其保持可搜索。 HTML/XML 标签 [lg]t; 文档中的 HTML/XML 代码示例里 和 在代码块中会被转义为 lt; 和 gt;。加入该子表达式后用户可以搜索到具体的标签名如 script。客户端实现中分隔符最终被编译为正则表达式赋给 lunr 分词器this.tokenizer tokenize as typeof lunr.tokenizer lunr.tokenizer.separator new RegExp(config.separator)见 Search 构造函数pipeline搜索索引的文本处理管道pipeline设置实验性默认自动计算用于指定管道函数——即在separator分词之后、写入索引之前对 token 进行的过滤与扩展处理。默认值根据站点语言自动计算也可以显式指定plugins: - search: pipeline: - stemmer - stopWordFilter - trimmer可用的管道函数如下stemmer– 将 token 词干化到词根形式例如把running归一为runstopWordFilter– 过滤常见停用词例如a、the等trimmer– 去除 token 两端的空白配置校验位于 SearchConfigpipeline只能是stemmer、stopWordFilter、trimmer三者组成的列表ListOfItems(Choice(...))。客户端 Search 类 会计算config.pipeline与默认三件套的差集并把未配置的管道函数从 lunr 的pipeline与searchPipeline中移除——例如你只配置stemmer则查询时不会做停用词过滤。Front Matter 元数据控制页面权重与排除search.boost提升或降低页面相关性search.boost8.3.0 起支持默认无用于调整页面在搜索结果中的相关度权重。大于1的值提高排名小于1的值降低排名 提升排名 yaml --- search: boost: 2 # (1)! --- # Page title ... 1. 提升页面权重时建议从较小的值开始尝试。 降低排名 yaml --- search: boost: 0.5 --- # Page title ... 从 create_entry_for_section 可以看到search.boost会作为boost字段写入索引条目客户端 Search.search 在检索后还会叠加「父文档加分 命中词占比」的二次加权score * (1 boost ** 2)并重新排序。值得一提的还有字段级默认权重。在 插件初始化 中如果未显式配置fields插件会注入三个默认字段title标题权重1e3text正文权重1e0tags标签权重1e6也就是说命中标题的文档默认显著优先于仅命中正文的文档而标签命中权重最高这解释了为何搜索结果中标题匹配往往排在最前。search.exclude将页面排除出索引search.exclude9.0.0 起支持默认无用于将页面从搜索结果中排除。注意这不仅移除页面本身还会一并移除该页面的所有子章节--- search: exclude: true --- # Page title ...对应实现位于 add_entry_from_context读取页面元数据中的search.exclude为真时直接返回、不生成任何索引条目。章节级排除data-search-exclude除整页排除外还可以通过data-search-excludepragma 在章节级别排除内容详见 构建站点搜索文档## Section 2 {>{ />配置参考与最佳实践小结完整的配置骨架可对照 搜索插件 JSON Schema 校验其lang支持的值与本文列出的语言表一致pipeline枚举限定为stemmer、stopWordFilter、trimmer。综合来看默认即用plugins: - search一行即可获得英文全文搜索语言与分隔符均随 站点语言 自动计算多语言站点通过lang显式声明语言列表注意每增加一种语言约多出 15-30kb 未压缩 JS 负载中文文档确保环境安装jieba构建期自动分词必要时用jieba_dict/jieba_dict_user微调分词效果检索体验调优用separator控制驼峰命名、版本号、HTML 标签的可检索性用pipeline决定是否启用词干化与停用词过滤结果排序治理用 Front Matter 的search.boost提升重点页面、search.exclude排除整页、{ contenteditable="false">【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考