/docusaurus-search-local

Offline/local search for Docusaurus v2

Primary LanguageTypeScriptMIT LicenseMIT

@easyops-cn/docusaurus-search-local

Npm Version CI Status Coverage Status

An offline/local search plugin for Docusaurus v2, which supports multiple languages, especially optimized for language of zh.

Originally forked from cmfcmf/docusaurus-search-local.

Then later fully rewritten with TypeScript 💪, styles polished 💅, language of Chinese supported 🇨🇳, and tests covered ✅.

Live Demo

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

Screen Shots

Screen Shot EN

Screen Shot ZH

Installation

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

Usage

Add @easyops-cn/docusaurus-search-local into your docusaurus plugins.

// In your `docusaurus.config.js`:
module.exports = {
  // ... Your other configurations.
  plugins: [
    // ... Your other plugins.
    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      {
        // ... Your options.
        // `hashed` is recommended as long-term-cache of index file is possible.
        hashed: true,
        // For Docs using Chinese, The `language` is recommended to set to:
        // ```
        // language: ["en", "zh"],
        // ```
        // When applying `zh` in language, please install `nodejieba` in your project.
      },
    ],
  ],
};

Notice!

When applying "zh" in language, please also install nodejieba in your project, it became a peer dependency since v0.7.0.

npm install nodejieba
# or
yarn add nodejieba

Plugin Options

Name Type Default Description
indexDocs boolean true Whether to index docs.
indexBlog boolean true Whether to index blog.
indexPages boolean false Whether to index pages.
docsRouteBasePath string | string[] "/docs" Base route path(s) of docs. Slash at beginning is not required.
blogRouteBasePath string | string[] "/blog" Base route path(s) of blog. Slash at beginning is not required.
language string | string[] "en" All lunr-languages supported languages, + zh 🔥.
hashed boolean false Whether to add a hashed query when fetching index (based on the content hash of all indexed *.md in docsDir and blogDir if applicable)
docsDir string | string[] "docs" The dir(s) of docs to get the content hash, it's relative to the dir of your project.
blogDir string | string[] "blog" Just like the docsDir but applied to blog.
removeDefaultStopWordFilter boolean false Sometimes people (E.g., us) want to keep the English stop words as indexed, since they maybe are relevant in programming docs.
highlightSearchTermsOnTargetPage boolean false Highlight search terms on target page.
searchResultLimits number 8 Limit the search results.
searchResultContextMaxLength number 50 Set the max length of characters of each search result to show.
translations TranslationMap - Set translations of this plugin, see docs below.
ignoreFiles string | RegExp | (string | RegExp)[] /meta$/ Set the match rules to ignore some files.

Translations

To make this plugin localized, pass a translations option which defaults to:

{
  "search_placeholder": "Search",
  "see_all_results": "See all results",
  "no_results": "No results.",
  "search_results_for": "Search results for \"{{ keyword }}\"",
  "search_the_documentation": "Search the documentation",
  "count_documents_found": "{{ count }} document found",
  "count_documents_found_plural": "{{ count }} documents found",
  "no_documents_were_found": "No documents were found"
}

Note that *_plural can be omitted if it is the same as singular.

Custom Styles

This plugin is shipped with polished styles just like the Algolia Search on the Docusaurus v2 website. Feel free to override these css custom properties (css variables) below.

Var Default (light) Default (dark)
--search-local-modal-background #f5f6f7 var(--ifm-background-color)
--search-local-modal-shadow inset 1px 1px 0 0 hsla(0, 0%, 100%, 0.5),
0 3px 8px 0 #555a64		 inset 1px 1px 0 0 #2c2e40,
0 3px 8px 0 #000309
--search-local-modal-width 560px -
--search-local-modal-width-sm 340px -
--search-local-spacing 12px -
--search-local-hit-background #fff var(--ifm-color-emphasis-100)
--search-local-hit-shadow 0 1px 3px 0 #d4d9e1 none
--search-local-hit-color #444950 var(--ifm-font-color-base)
--search-local-hit-height 56px -
--search-local-highlight-color var(--ifm-color-primary) -
--search-local-muted-color #969faf var(--ifm-color-secondary-darkest)
--search-local-icon-stroke-width 1.4 -
--search-local-hit-active-color var(--ifm-color-white) -

E.g.:

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

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

Trouble Shooting

When building your docs project, Set the env DEBUG=search-local:* to enable debug logs.

# In your docs project:
DEBUG=search-local:* yarn build

In case some specific errors occurred:

  • Error: Cannot mix different versions of joi schemas:
    • Try using @easyops-cn/docusaurus-search-local >= v0.16.0 with Docusaurus >= v2.0.0-alpha.73
    • Try using @easyops-cn/docusaurus-search-local between v0.14.0 and v0.15.1 with Docusaurus between v2.0.0-alpha.68 and v2.0.0-alpha.72
    • Or try using @easyops-cn/docusaurus-search-local <= v0.13.1 with Docusaurus <= v2.0.0-alpha.66
  • Error: Command failed with signal "SIGSEGV":
    • This is probably caused by a known issue introduced by nodejieba@2.5.2, if you enabled language of zh.
    • Try downgrading nodejieba to 2.4.2 and it will work again, see discussions in #47.

Further Reading

Contributing

See contributing guide.