mkdocs 中文搜索同义词¶

目的：为中文用户加搜索同义词关联：[B1-8]

1. 问题¶

mkdocs search 默认只支持精确匹配： - 用户搜"权限" → 找不到 "Permission" - 用户搜"性能" → 找不到 "Performance"

2. 解决方案¶

mkdocs-material 支持 search.lang 和 synonym 配置。

3. 4 步配置¶

3.1 Step 1: yaml 配置¶

# mkdocs.yml
theme:
  name: material
  features:
    - search.suggest
    - search.highlight
    - search.share
  language: zh

language: zh —— 中文分词。

3.2 Step 2: 配置搜索¶

plugins:
  - search:
      lang:
        - en
        - zh
      separator: '[\s\-\.]+'

多语言。

3.3 Step 3: 同义词文件¶

# mkdocs.yml
extra:
  search:
    synonym:
      权限: [permission, permissions, authorize]
      性能: [performance, perf, speed]
      安全: [security, secure, sec]
      鉴权: [auth, authentication, authorize]

5 同义词。

3.4 Step 4: 测试¶

mkdocs serve
# 浏览器搜 "权限" → 应找到 permission 相关

测。

4. 5 个同义词集¶

synonym:
  权限: [permission, permissions, authorize]
  性能: [performance, perf, speed, fast]
  安全: [security, secure, sec, safety]
  鉴权: [auth, authentication, authorize, oauth]
  插件: [plugin, plugins, extension, add-on]

5 集。

5. 5 个最佳实践¶

中英对照 —— 双向同义词
具体术语 —— 不要太宽
持续更新 —— 新术语加
测 search —— 验证
不要太多 —— 5-10 个核心

6. 总结¶

中文搜索 = 4 步配置 + 5 同义词集。

下一步： - 看 B1-9 requirements-docs.txt