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.

• Example:

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

• Also see:
  • Guide > I18n

hotKeys

• Type: (string | KeyOptions)[]

  export interface KeyOptions {
    /**
     * Value of `event.key` to trigger the hot key
     *
     * 热键的 `event.key` 值
     */
    key: string
  
    /**
     * Whether to press `event.altKey` at the same time
     *
     * 是否同时按下 `event.altKey`
     *
     * @default false
     */
    alt?: boolean
  
    /**
     * Whether to press `event.ctrlKey` at the same time
     *
     * 是否同时按下 `event.ctrlKey`
     *
     * @default false
     */
    ctrl?: boolean
  
    /**
     * Whether to press `event.shiftKey` at the same time
     *
     * 是否同时按下 `event.shiftKey`
     *
     * @default false
     */
    shift?: boolean
  
    /**
     * Whether to press `event.metaKey` at the same time
     *
     * 是否同时按下 `event.metaKey`
     *
     * @default false
     */
    meta?: 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-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