https://github.com/gabrielcsapo/docusaurus-plugin-search-local
An offline/local search plugin for Docusaurus v2
https://github.com/gabrielcsapo/docusaurus-plugin-search-local
docusaurus local search
Last synced: 10 months ago
JSON representation
An offline/local search plugin for Docusaurus v2
- Host: GitHub
- URL: https://github.com/gabrielcsapo/docusaurus-plugin-search-local
- Owner: gabrielcsapo
- License: mit
- Created: 2021-09-07T20:48:53.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-28T15:12:06.000Z (over 1 year ago)
- Last Synced: 2025-04-08T23:48:20.573Z (about 1 year ago)
- Topics: docusaurus, local, search
- Language: TypeScript
- Homepage: https://gabrielcsapo.github.io/docusaurus-plugin-search-local/
- Size: 8.39 MB
- Stars: 26
- Watchers: 2
- Forks: 8
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# docusaurus-plugin-search-local
[](https://www.npmjs.com/package/docusaurus-plugin-search-local)
[](https://github.com/easyops-cn/docusaurus-search-local/actions?query=workflow%3ACI)
[](https://coveralls.io/github/easyops-cn/docusaurus-search-local?branch=master)
An offline/local search plugin for [Docusaurus v2](https://v2.docusaurus.io/), which supports multiple languages.
> Originally forked from [cmfcmf/docusaurus-search-local](https://github.com/cmfcmf/docusaurus-search-local).
>
> Then later fully rewritten with TypeScript 💪, styles polished 💅, and tests covered ✅.
- [Live Demo](#live-demo)
- [Screen Shots](#screen-shots)
- [Installation](#installation)
- [Usage](#usage)
- [Plugin Options](#plugin-options)
- [Custom Styles](#custom-styles)
- [Trouble Shooting](#trouble-shooting)
- [Further Reading](#further-reading)
- [Contributing](#contributing)
## Live Demo
[https://gabrielcsapo.github.io/docusaurus-plugin-search-local/](https://gabrielcsapo.github.io/docusaurus-plugin-search-local/)
## Installation
```shell
npm install --save docusaurus-plugin-search-local
# or
yarn add docusaurus-plugin-search-local
```
## Usage
Add `docusaurus-plugin-search-local` into your docusaurus plugins.
````js
// In your `docusaurus.config.js`:
module.exports = {
// ... Your other configurations.
plugins: [
// ... Your other plugins.
[
require.resolve('docusaurus-plugin-search-local'),
{
// ... Your options.
// `hashed` is recommended as long-term-cache of index file is possible.
hashed: true,
// ```
// language: ["en", "de"],
// ```
},
],
],
};
````
## 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](https://github.com/MihaiValentin/lunr-languages) supported languages. |
| 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](#translations). |
| 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:
```json
{
"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.:
```css
:root {
--search-local-modal-width: 480px;
--search-local-highlight-color: #5468ff;
}
html[data-theme='dark'] {
--search-local-highlight-color: #d23669;
}
```
## Troubleshooting
When building your docs project, Set the env `DEBUG=docusaurus-plugin-search-local:*` to enable [debug](https://github.com/visionmedia/debug) logs.
```shell
# In your docs project:
DEBUG=docusaurus-plugin-search-local:* yarn build
```
## Contributing
See [contributing guide](CONTRIBUTING.md).