search

Provide local search to your documentation site.

Usage

npm i -D @vuepress/plugin-search@next

import { searchPlugin } from '@vuepress/plugin-search'

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

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

locales

• Type: Record<string, { placeholder: string }>

• Details:

  The text of the search box in different locales.

  If this option is not specified, it will fallback to default text.

• Example:

export default {
  plugins: [
    searchPlugin({
      locales: {
        '/': {
          placeholder: 'Search',
        },
        '/zh/': {
          placeholder: '搜索',
        },
      },
    }),
  ],
}

• Also see:
  • Guide > I18n

hotKeys

• Type: (string | HotKeyOptions)[]

export interface HotKeyOptions {
  /**
   * Value of `event.key` to trigger the hot key
   */
  key: string

  /**
   * Whether to press `event.altKey` at the same time
   *
   * @default false
   */
  alt?: boolean

  /**
   * Whether to press `event.ctrlKey` at the same time
   *
   * @default false
   */
  ctrl?: boolean

  /**
   * Whether to press `event.shiftKey` at the same time
   *
   * @default false
   */
  shift?: boolean
}

• Default: ['s', '/']

• Details:

  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.

maxSuggestions

• Type: number

• Default: 5

• Details:

  Specify the maximum number of search results.

isSearchable

• Type: (page: Page) => boolean

• Default: () => true

• Details:

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

  • Return true to include the page.
  • Return false to exclude the page.

• Example:

export default {
  plugins: [
    searchPlugin({
      // exclude the homepage
      isSearchable: (page) => page.path !== '/',
    }),
  ],
}

getExtraFields

• Type: (page: Page) => string[]

• Default: () => []

• Details:

  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.

• Example:

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-border: var(--vp-c-gutter);
  --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