跳转至

一次在github上询问作者的经历

约 676 个字 • 17 行代码

2023-09-11

Why does mkdocs-material display unsupported Chinese when running the mkdocs gh-deploy -- force command · squidfunk/mkdocs-material · Discussion #5992 (github.com)

stage 1

作者让创建一个最小复制件然后上传，

Creating a reproduction - Material for MkDocs (squidfunk.github.io)

我大致的操作过程是，创建一个新的mkdocs项目，然后按文档说的 在 mkdocs.yml 文件中添加必要的配置，

  • 基本上必须的

    theme:
  name: material

  • 报错的地方

    plugins:
  - search:
      jieba_dict: jieba_dict/dict.txt.big
      jieba_dict_user: jieba_dict/user_dict.txt
      lang: 
        - zh

然后 mkdocs build 一下，出现了报错，(如果没有应该就是继续按原来的配置添加可能导致报错的配置，不断尝试直到出现报错)

再按文档说的，添加生成错误报告的插件

plugins:
  - info

最后再 mkdocs build 一次，但是这次需要能连接上 github (要挂梯子)，然后会在项目根目录生成一个 zip 文件

mkdocs_bug_report

stage 2

作者回复，将 search 中的 lang 选项全部去除即可

但在我去除后，仍产生了一行报错

...
WARNING - Language 'zh' is not supported by Lunr.js, not setting it in the 'plugins.search.lang' option
...

怀疑是由于使用了语言切换的插件 i18n 中设置的 zh 导致的，

将插件的配置代码注释掉之后，再次配置，发现报错信息消失(所以确定报错信息是由于在i18n插件中设置了 zh 相关的配置产生的)

在查看了 mkdocs-static-i18n 的官方文档(Installation - MkDocs static i18n plugin documentation (en) (ultrabug.github.io))之后，发现插件有个选项可以不更改mkdocs-material原有的内置search插件的配置

Setting up search - MkDocs static i18n plugin documentation (en) (ultrabug.github.io)

然后发现这是新版本才有的选项，所以将原有版本 v0.5.6 更新为 v1.0.3 ，但新版本的语言配置也改变，Setting up languages - MkDocs static i18n plugin documentation (en) (ultrabug.github.io)，

(其余的一些关于新版变化的发现可见于手册18)

经过调整和选项的设置，最后报错信息消失了。

但是搜索功能的中文分割仍然不能用，向作者再次询问

stage 3

作者回复他尝试了，可以正常使用

经过尝试，发现需要将 theme 设置中的 language 设置成 zh 才能使搜索的中文支持正常(不加就不行)，并向作者反映

作者回复，因为设置了 language: zh 会自动配置搜索分割(search separator)，如果没有设置 language: zh ，则需要手动添加相应的搜索分割(search separator)，参考Chinese search support - Material for MkDocs (squidfunk.github.io)

但是我看到他给出的github里的文件里，设置的的分割要更多( "search.config.separator": "[\\s\\u200b\\u3000\\-、。，．？！；]+", )，所以我选取了那个文件里的配置添加到我的 mkdocs.yml 文件里

  - search:
      separator: '[\\s\\u200b\\u3000\\-、。，．？！；\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'

原本为：

  - search:
      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'

经过测试，搜索中文支持能够正常使用，并且 i18n 插件也能正常使用

最后更新: 2023-10-04
创建日期: 2023-09-13

评论