@easyops-cn/docusaurus-search-local

这是一个为 Docusaurus v2/v3 设计的离线/本地搜索插件/主题，支持多种语言，特别针对中文进行了优化。

最初从 cmfcmf/docusaurus-search-local 分叉而来。

之后使用 TypeScript 完全重写 💪，样式进行了优化 💅，支持中文 🇨🇳，并进行了测试覆盖 ✅。

• 在线演示
• 截图
• 安装
• 使用方法
• 主题选项
• 自定义样式
• 故障排除
• 进一步阅读
• 贡献

在线演示

https://easyops-cn.github.io/docusaurus-search-local/

截图

安装

npm install --save @easyops-cn/docusaurus-search-local
# 或
yarn add @easyops-cn/docusaurus-search-local

使用方法

将 @easyops-cn/docusaurus-search-local 添加到你的 docusaurus 主题中。

// 在你的 `docusaurus.config.js` 中：
module.exports = {
  // ... 你的其他配置。
  themes: [
    // ... 你的其他主题。
    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
      ({
        // ... 你的选项。
        // 只要可以长期缓存索引文件，就推荐使用 `hashed`。
        hashed: true,
        // 对于使用中文的文档，建议将 `language` 设置为：
        // ```
        // language: ["en", "zh"],
        // ```
      }),
    ],
  ],
};

注意：我们现在将其作为主题而不是插件呈现，请参阅此评论。

主题选项

国际化

从 v0.25.0 版本开始，我们支持 Docusaurus 国际化系统，并默认提供了英语、德语、越南语和简体中文的翻译。

对于其他语言，请按照官方教程学习如何翻译插件数据。并在 i18n/*/code.json 中翻译 theme.SearchBar.* 和 theme.SearchPage.*。

从 v0.25.0 版本开始，不再支持通过选项进行翻译。

{
  "translations": {
    "search_placeholder": "搜索",
    "see_all_results": "查看所有结果",
    "no_results": "无结果。",
    "search_results_for": "搜索 \"{{ keyword }}\" 的结果",
    "search_the_documentation": "搜索文档",
    "count_documents_found": "找到 {{ count }} 个文档",
    "count_documents_found_plural": "找到 {{ count }} 个文档",
    "no_documents_were_found": "未找到文档"
  }
}

自定义样式

这个主题附带了精心设计的样式，就像 Docusaurus v2 网站上的 Algolia 搜索一样。您可以自由覆盖以下这些 CSS 自定义属性（CSS 变量）。

例如：

:root {
  --search-local-modal-width: 480px;
  --search-local-highlight-color: #5468ff;
}

html[data-theme="dark"] {
  --search-local-highlight-color: #d23669;
}

故障排除

在构建文档项目时，设置环境变量 DEBUG=search-local:* 以启用 debug 日志。

# 在您的文档项目中：
DEBUG=search-local:* yarn build

如果遇到一些特定错误：

• Error: Cannot mix different versions of joi schemas：

  • 尝试使用 @easyops-cn/docusaurus-search-local >= v0.16.0 搭配 Docusaurus >= v2.0.0-alpha.73
  • 尝试使用 @easyops-cn/docusaurus-search-local v0.14.0 到 v0.15.1 搭配 Docusaurus v2.0.0-alpha.68 到 v2.0.0-alpha.72
  • 或者尝试使用 @easyops-cn/docusaurus-search-local <= v0.13.1 搭配 Docusaurus <= v2.0.0-alpha.66

• 模块未找到：错误：无法解析 '@docusaurus/useRouteContext'：

  • 尝试在 Docusaurus >= v2.0.0-beta.18 版本中使用 @easyops-cn/docusaurus-search-local >= v0.25.0
  • 尝试在 Docusaurus < v2.0.0-beta.18 版本中使用 @easyops-cn/docusaurus-search-local < v0.25.0

延伸阅读

• 多语言全文搜索

贡献

请参阅贡献指南。