docusaurus-plugin-search-local

An offline/local search plugin for Docusaurus v2, which supports multiple languages.

Originally forked from cmfcmf/docusaurus-search-local.

Then later fully rewritten with TypeScript 💪, styles polished 💅, and tests covered ✅.

• Live Demo
• Screen Shots
• Installation
• Usage
• Plugin Options
• Custom Styles
• Trouble Shooting
• Further Reading
• Contributing

Live Demo

https://gabrielcsapo.github.io/docusaurus-plugin-search-local/

Installation

npm install --save docusaurus-plugin-search-local
# or
yarn add docusaurus-plugin-search-local

Usage

Add docusaurus-plugin-search-local into your docusaurus plugins.

// 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 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.
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;
}

Troubleshooting

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

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

Contributing

See contributing guide.