search

@vuepress/plugin-search

Provide local search to your documentation site.

Usage

npm i -D @vuepress/plugin-search@next
.vuepress/config.ts
import { searchPlugin } from '@vuepress/plugin-search'

export default {
  plugins: [
    searchPlugin({
      // options
    }),
  ],
}

Guide

Local Search Index

This plugin will generate search index from your pages locally, and load the search index file when users enter your site. In other words, this is a lightweight built-in search which does not require any external requests.

However, when your site has a large number of pages, the size of search index file would be very large, which could slow down the page loading speed. In this case, we recommend you to use a more professional solution - docsearch.

Options

localesLocaleConfig<SearchPluginLocaleData>
Default{}

The text of the search box in different locales.

See also: Locales.

locales.<localePath>.placeholderstring

The placeholder of the search box.

hotKeys(KeyOptions | string)[]
Default['s', '/']

Specify the event.key of the hotkeys. When hotkeys are pressed, the search box input will be focused. Set to an empty array to disable hotkeys.

hotKeys[*].keyRequiredstring

Value of event.key to trigger the hot key.

hotKeys[*].ctrlboolean

Whether to press event.ctrlKey at the same time.

hotKeys[*].shiftboolean

Whether to press event.shiftKey at the same time.

hotKeys[*].altboolean

Whether to press event.altKey at the same time.

hotKeys[*].metaboolean

Whether to press event.metaKey at the same time.

maxSuggestionsnumber
Default5

Specify the maximum number of search results.

isSearchable(page: Page) => boolean
Default() => true

A function to determine whether a page should be included in the search index.

.vuepress/config.ts
export default {
  plugins: [
    searchPlugin({
      // exclude the homepage
      isSearchable: (page) => page.path !== '/',
    }),
  ],
}
getExtraFields(page: Page) => string[]
Default() => []

A function to add extra fields to the search index of a page.

By default, this plugin will use page title and headers as the search index. This option could help you to add more searchable fields.

.vuepress/config.ts
export default {
  plugins: [
    searchPlugin({
      // allow searching the `tags` frontmatter
      getExtraFields: (page) => page.frontmatter.tags ?? [],
    }),
  ],
}

Styles

You can customize the style of the search box via CSS variables:

:root {
  --search-c-bg: var(--vp-c-bg);
  --search-c-accent: var(--vp-c-accent);
  --search-c-text: var(--vp-c-text);
  --search-c-divider: var(--vp-c-divider);
  --search-c-item-text: var(--vp-c-text-subtle);
  --search-c-item-focus: var(--vp-c-bg-alt);
  --search-input-width: 8rem;
  --search-result-width: 20rem;
}

Components

  • SearchBox