docusaurus-search-local - GitLite

KO | EN

gitlite — search

#javascript #react #llm #go #deep-learning #linux #docker #nodejs #awesome #kubernetes #vue #awesome-list #pytorch #ios

docusaurus-search-local

(★ 898)

Offline/local search for Docusaurus v2/v3

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
  - gh-pages.yml
  - release-please.yml
- pre-commit
- - yarn-4.12.0.cjs
- - integrations.yml
- Translate.js
- - ar.json
  - de.json
  - ja.json
  - vi.json
  - zh-Hans.json
- - declarations.ts
  - index.ts
- CHANGELOG.md
- package.json
- README.md
- tsconfig.client.json
- tsconfig.json
- tsconfig.server.json
- tsconfig.types.json
- ask-ai-01.png
- ask-ai-02.png
- screen-shot-en.png
- screen-shot-zh.png
- - 2019-05-28-hola.md
  - 2019-05-29-hello-world.md
  - 2019-05-30-welcome.md
  - 2019-06-15-writing-good-unit-tests.md
- - intro.md
  - unlisted-post.md
- - .nojekyll
- - version-1.0.0-sidebars.json
- babel.config.js
- docusaurus.config.js
- package.json
- README.md
- renovate.json
- sidebars.js
- versions.json
- - 2019-05-28-first-blog-post.md
  - 2019-05-29-long-blog-post.md
  - 2021-08-01-mdx-blog-post.mdx
  - authors.yml
- - resources.md
- - intro.md
- - .nojekyll
- babel.config.js
- docusaurus.config.js
- package.json
- README.md
- sidebars.js
- sidebarsCommunity.js
.editorconfig
.eslintignore
.eslintrc
.gitignore
.huskyrc
.lintstagedrc
.yarnrc.yml
babel.config.js
CONTRIBUTING.md
jest.config.js
jestSetup.js
LICENSE
package.json
README.md
release-please-config.json
renovate.json
yarn.lock

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/easyops-cn/docusaurus-search-local

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd docusaurus-search-local

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install --save open-ask-ai

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

yarn add open-ask-ai

이 명령어를 터미널에 그대로 입력해 실행하세요.

npm install --save @easyops-cn/docusaurus-search-local

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

yarn add @easyops-cn/docusaurus-search-local

이 명령어를 터미널에 그대로 입력해 실행하세요.

DEBUG=search-local:* yarn build

배포용으로 코드를 최적화해서 빌드 파일을 생성합니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# @easyops-cn/docusaurus-search-local

[![Npm Version](https://img.shields.io/npm/v/@easyops-cn/docusaurus-search-local)](https://www.npmjs.com/package/@easyops-cn/docusaurus-search-local)
[![CI Status](https://github.com/easyops-cn/docusaurus-search-local/workflows/gh-pages/badge.svg?event=push&branch=master)](https://github.com/easyops-cn/docusaurus-search-local/actions?query=workflow%3Agh-pages)
[![Coverage Status](https://coveralls.io/repos/github/easyops-cn/docusaurus-search-local/badge.svg?branch=master)](https://coveralls.io/github/easyops-cn/docusaurus-search-local?branch=master)

An offline/local search plugin/theme for [Docusaurus v2/v3](https://docusaurus.io/), which supports multiple languages, especially optimized for language of zh.

> Originally forked from [cmfcmf/docusaurus-search-local](https://github.com/cmfcmf/docusaurus-search-local).
>
> Then later fully rewritten with TypeScript 💪, styles polished 💅, language of Chinese supported 🇨🇳, and tests covered ✅.

- [Live Demo](#live-demo)
- [Screen Shots](#screen-shots)
- [Installation](#installation)
- [Usage](#usage)
- [Theme Options](#theme-options)
- [Custom Styles](#custom-styles)
- [Trouble Shooting](#trouble-shooting)
- [Further Reading](#further-reading)
- [Contributing](#contributing)

## Live Demo

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

## Screen Shots

<p align="center">
  <img src="screen-shots/screen-shot-en.png" alt="Screen Shot EN" width="591" />
</p>

<p align="center">
  <img src="screen-shots/screen-shot-zh.png" alt="Screen Shot ZH" width="602" />
</p>

## ✨ Ask AI Support

This plugin now supports **Ask AI** integration! Enable AI-powered assistance directly in your documentation site to help users get instant, context-aware answers.

NOTE: Ask AI feature requires an external AI service. Please refer to the [Open Ask AI Server](https://github.com/easyops-cn/open-ask-ai-server), which is a serverless solution, and can be used **for free** using Vercel Hobby Plan!

### Installing Ask AI

The Ask AI feature is **opt-in**. To enable it, you need to install the `open-ask-ai` package separately:

```shell
npm install --save open-ask-ai
# or
yarn add open-ask-ai
```

<p align="center">
  <img src="screen-shots/ask-ai-01.png" alt="Ask AI Screenshot 1" width="602" />
</p>

<p align="center">
  <img src="screen-shots/ask-ai-02.png" alt="Ask AI Screenshot 2" width="631" />
</p>

With Ask AI enabled, users can:

- Get intelligent answers based on your documentation
- Access AI assistance with a simple keyboard shortcut
- Receive context-aware responses tailored to your content

See the [askAi option](#theme-options) in Theme Options below for configuration details.

## Installation

```shell
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 themes.

```js
// In your `docusaurus.config.js`:
module.exports = {
  // ... Your other configurations.
  themes: [
    // ... Your other themes.
    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
      ({
        // ... Your options.
        // `hashed` is recommended as long-term-cache of index file is possible.
        hashed: true,

// For Docs using Chinese, it is recomended to set:
        // language: ["en", "zh"],

// Customize the keyboard shortcut to focus search bar (default is "mod+k"):
        // searchBarShortcutKeymap: "s", // Use 'S' key
        // searchBarShortcutKeymap: "ctrl+shift+f", // Use Ctrl+Shift+F

// If you're using `noIndex: true`, set `forceIgnoreNoIndex` to enable local index:
        // forceIgnoreNoIndex: true,

// Enable Ask AI integration:
        // askAi: {
        //   project: "your-project-name",
        //   apiUrl: "https://your-api-url.com/api/stream",
        //   hotkey: "cmd+I", // Optional: keyboard shortcut to trigger Ask AI
        // },
      }),
    ],
  ],
};
```

> Notice: We present this as a theme instead of plugin now, see [this comment](https://github.com/facebook/docusaurus/issues/6488#issuecomment-1024124096).

## Theme 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. Note: for [docs-only mode](https://docusaurus.io/docs/docs-introduction#docs-only-mode), this needs to be the same as `routeBasePath` in your `@docusaurus/preset-classic` config e.g., `"/"`.                                                                                              |
| blogRouteBasePath                 | string \| string[]                                                          | `"/blog"` | Base route path(s) of blog. Slash at beginning is not required.                                                                                                                                                                                                                                                                                             |
| language                          | string \| string[]                                                          | `"en"`    | All [lunr-languages](https://github.com/MihaiValentin/lunr-languages) supported languages, + `zh` 🔥.                                                                                                                                                                                                                                                       |
| hashed                            | boolean \| `"filename"` \| `"query"`                                        | `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). Setting to `"filename"` will save hash in filename instead of query.                                                                                                                                          |
| 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 \| string[]                                                         | `[]`      | Sometimes people (E.g., us) want to keep the English stop words as indexed, since they maybe are relevant in programming docs. Set a language list to remove their default stop word filter, `true` is equivalent to `["en"]`.                                                                                                                              |
| removeDefaultStemmer              | boolean                                                                     | `false`   | Enable this if you want to be able to search for any partial word at the cost of search performance.                                                                                                                                                                                                                                                        |
| 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.                                                                                                                                                                                                                                                                                             |
| explicitSearchResultPath          | boolean                                                                     | `false`   | Whether an explicit path to a heading should be presented on a suggestion template.                                                                                                                                                                                                                                                                         |
| ignoreFiles                       | string \| RegExp \| (string \| RegExp)[]                                    | `[]`      | Set the match rules to ignore some routes. Put a string if you want an exact match, or put a regex if you want a partial match. Note: without the website base url.                                                                                                                                                                                         |
| ignoreCssSelectors                | string \| string[]                                                          | `[]`      | A list of css selectors to ignore when indexing each page.                                                                                                                                                                                                                                                                                                  |
| searchBarShortcut                 | boolean                                                                     | `true`    | Whether to enable keyboard shortcut to focus in search bar.                                                                                                                                                                                                                                                                                                 |
| searchBarShortcutHint             | boolean                                                                     | `true`    | Whether to show keyboard shortcut hint in search bar. Disable it if you need to hide the hint while shortcut is still enabled.                                                                                                                                                                                                                              |
| searchBarShortcutKeymap           | string                                                                      | `"mod+k"` | Custom keyboard shortcut to focus the search bar. Supports formats like: `"s"` for single key, `"ctrl+k"` for key combinations, `"mod+k"` for Command+K (Mac) / Ctrl+K (others) - recommended cross-platform option, `"ctrl+shift+k"` for multiple modifiers.                                                                                               |
| searchBarPosition                 | `"auto"` \| `"left"` \| `"right"`                                           | `"auto"`  | The side of the navbar the search bar should appear on. By default, it will try to autodetect based on your docusaurus config according to [the docs](https://docusaurus.io/docs/api/themes/configuration#navbar-search).                                                                                                                                   |
| docsPluginIdForPreferredVersion   | string                                                                      |           | When you're using multi-instance of docs, set the docs plugin id which you'd like to check the preferred version with, for the search index.                                                                                                                                                                                                                |
| zhUserDict                        | string                                                                      |           | Provide your custom dict for language of zh, [see here](https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8)                                                                                                                                                                                                                                |
| zhUserDictPath                    | string                                                                      |           | Provide the file path to your custom dict for language of zh, E.g.: `path.resolve("./src/zh-dict.txt")`                                                                                                                                                                                                                                                     |
| searchContextByPaths              | `(string \| { label: string \| Record<string, string>; path: string; } )[]` | `[]`      | Provide an list of sub-paths as separate search context, E.g.: `["docs", "community", "legacy/resources"]`. It will create multiple search indexes by these paths.                                                                                                                                                                                          |
| hideSearchBarWithNoSearchContext  | boolean                                                                     | `false`   | Whether to hide the search bar when no search context was matched. By default, if `searchContextByPaths` is set, pages which are not matched with it will be considered as with a search context of ROOT. By setting `hideSearchBarWithNoSearchContext: true`, these pages will be considered as with NO search context, and the search bar will be hidden. |
| useAllContextsWithNoSearchContext | boolean                                                                     | `false`   | Whether to show results from all the contexts if no context is provided. This option should not be used with `hideSearchBarWithNoSearchContext: true` as this would show results when there is no search context. This will duplicate indexes and might have a performance cost depending on the index sizes.                                               |
| `forceIgnoreNoIndex`              | boolean                                                                     | `false`   | Force enable search index even if `noIndex: true` is set, this also affects unlisted articles.                                                                                                                                                                                                                                                              |
| `fuzzyMatchingDistance`           | number                                                                      | `1`       | Set the edit distance for fuzzy matching during searches.                                                                                                                                                                                                                                                                                                   |
| `askAi`                           | object                                                                      |           | Configuration for Ask AI widget integration. When not set, the Ask AI feature will be disabled. Required properties: `project` (string), `apiUrl` (string). Optional: `hotkey` (string, e.g., "cmd+I"). See [Ask AI Support](#-ask-ai-support) for more details.                                                                                            |

### I18N

Since v0.25.0, we support [docusaurus i18n system](<(https://docusaurus.io/docs/i18n/introduction)>), and provided `en` / `de` / `vi` and `zh-CN` translations out of the box.

For other languages, please follow the official tutorial about how to [translate plugin data](https://docusaurus.io/docs/i18n/tutorial#translate-plugin-data). And translate `theme.SearchBar.*` and `theme.SearchPage.*` in `i18n/*/code.json`.

Translations by options is dropped since v0.25.0.

<details>
<summary>See translation options for &lt;0.25.0</summary>
To make this theme localized, pass a `translations` option which defaults to:

```json
{
  "translations": {
    "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.

</details>

## Custom Styles

This theme 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                                      | Description                               | Default (light)                                                        | Default (dark)                                          |
| ---------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------- |
| --search-local-modal-background          | The search modal background               | `#f5f6f7`                                                              | `var(--ifm-background-color)`                           |
| --search-local-modal-shadow              | The search modal box-shadow               | `inset 1px 1px 0 0 hsla(0, 0%, 100%, 0.5),`<br />`0 3px 8px 0 #555a64` | `inset 1px 1px 0 0 #2c2e40,`<br />`0 3px 8px 0 #000309` |
| --search-local-modal-width               | The width of search modal by default      | `560px`                                                                | -                                                       |
| --search-local-modal-width-sm            | The width of search modal on small screen | `340px`                                                                | -                                                       |
| --search-local-spacing                   | The padding fo search modal               | `12px`                                                                 | -                                                       |
| --search-local-hit-background            | The background of each suggestion         | `#fff`                                                                 | `var(--ifm-color-emphasis-100)`                         |
| --search-local-hit-shadow                | The box-shadow of each suggestion         | `0 1px 3px 0 #d4d9e1`                                                  | `none`                                                  |
| --search-local-hit-color                 | The text color of suggestions             | `#444950`                                                              | `var(--ifm-font-color-base)`                            |
| --search-local-hit-height                | The height of each suggestion             | `56px`                                                                 | -                                                       |
| --search-local-highlight-color           | The highlight text color of suggestions   | `var(--ifm-color-primary)`                                             | -                                                       |
| --search-local-muted-color               | The text color of some secondary content  | `#969faf`                                                              | `var(--ifm-color-secondary-darkest)`                    |
| --search-local-icon-stroke-width         | The icon stroke width of suggestions      | `1.4`                                                                  | -                                                       |
| --search-local-hit-active-color          | The text color of selected suggestion     | `var(--ifm-color-white)`                                               | -                                                       |
| --search-local-input-active-border-color | The border color of input box when active | `var(--ifm-color-primary)`                                             | -                                                       |

E.g.:

```css
: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](https://github.com/visionmedia/debug) logs.

```shell
# 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

- `Module not found: Error: Can't resolve '@docusaurus/useRouteContext'`:
  - Try using @easyops-cn/docusaurus-search-local >= v0.25.0 with Docusaurus >= v2.0.0-beta.18
  - Try using @easyops-cn/docusaurus-search-local < v0.25.0 with Docusaurus < v2.0.0-beta.18

## Further Reading

- [多语言全文搜索](https://wangshenwei.com/multilingual-full-text-search/)

## Contributing

See [contributing guide](CONTRIBUTING.md).