10 KiB

Raw Blame History Unescape Escape

outline
deep

検索

ローカル検索

VitePress は、minisearch によるブラウザ内インデックスを使った曖昧一致の全文検索をサポートします。有効化するには、.vitepress/config.ts で themeConfig.search.provider を 'local' に設定します。

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
})

表示例:

代わりに Algolia DocSearch や、次のコミュニティ製プラグインを使うこともできます。

i18n

多言語検索を行う設定例です。

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        locales: {
          ja: { // 既定ロケールを翻訳する場合は `root` にしてください
            translations: {
              button: {
                buttonText: '検索',
                buttonAriaLabel: '検索'
              },
              modal: {
                displayDetails: '詳細一覧を表示',
                resetButtonTitle: '検索をリセット',
                backButtonTitle: '検索を閉じる',
                noResultsText: '結果が見つかりません',
                footer: {
                  selectText: '選択',
                  selectKeyAriaLabel: 'Enter',
                  navigateText: '移動',
                  navigateUpKeyAriaLabel: '上矢印',
                  navigateDownKeyAriaLabel: '下矢印',
                  closeText: '閉じる',
                  closeKeyAriaLabel: 'Esc'
                }
              }
            }
          }
        }
      }
    }
  }
})

miniSearch のオプション

MiniSearch の設定例です。

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        miniSearch: {
          /**
           * @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
           */
          options: {
            /* ... */
          },
          /**
           * @type {import('minisearch').SearchOptions}
           * @default
           * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
           */
          searchOptions: {
            /* ... */
          }
        }
      }
    }
  }
})

詳しくは MiniSearch のドキュメントを参照してください。

コンテンツレンダラーのカスタマイズ

インデックス前に Markdown コンテンツをレンダリングする関数をカスタマイズできます。

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        /**
         * @param {string} src
         * @param {import('vitepress').MarkdownEnv} env
         * @param {import('markdown-it-async')} md
         */
        async _render(src, env, md) {
          // HTML 文字列を返す
        }
      }
    }
  }
})

この関数はクライアント側のサイトデータからは除外されるため、Node.js の API を使用できます。

例: 検索対象からページを除外する

フロントマターに search: false を追加すると、そのページを検索対象から除外できます。あるいは次のようにもできます。

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        async _render(src, env, md) {
          const html = await md.renderAsync(src, env)
          if (env.frontmatter?.search === false) return ''
          if (env.relativePath.startsWith('some/path')) return ''
          return html
        }
      }
    }
  }
})

::: warning 注意カスタムの _render 関数を提供する場合、search: false の処理は自分で行う必要があります。また、env は md.renderAsync の呼び出し前には完全ではないため、frontmatter などの任意プロパティのチェックはその後に行ってください。 :::

例: コンテンツの変換 — 見出しアンカーを追加

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        async _render(src, env, md) {
          const html = await md.renderAsync(src, env)
          if (env.frontmatter?.title)
            return await md.renderAsync(`# ${env.frontmatter.title}`) + html
          return html
        }
      }
    }
  }
})

Algolia 検索

VitePress は Algolia DocSearch によるサイト検索をサポートします。導入は公式のガイドを参照してください。.vitepress/config.ts では最低限次の設定が必要です。

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...'
      }
    }
  }
})

i18n

多言語検索の設定例です。

クリックして展開

<<< @/snippets/algolia-i18n.ts

詳しくは公式 Algolia ドキュメントを参照してください。すぐに始めるには、このサイトで使っている翻訳をGitHub リポジトリからコピーすることもできます。

Algolia Ask AI のサポート

Ask AI を有効にするには、options 内に askAi オプション（またはその一部）を指定します。

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        // askAi: "あなたのアシスタントID"
        // または
        askAi: {
          // 最低限、Algolia から受け取った assistantId を指定する必要があります
          assistantId: 'XXXYYY',
          // 任意の上書き — 省略した場合は上位の appId/apiKey/indexName を再利用
          // apiKey: '...',
          // appId: '...',
          // indexName: '...'
        }
      }
    }
  }
})

::: warning 注意キーワード検索を既定にして Ask AI を使わない場合は、askAi を指定しないでください。 :::

Ask AI サイドパネル

DocSearch v4.5+ はオプションの Ask AI サイドパネルをサポートしています。有効にすると、デフォルトで Ctrl/Cmd+I で開くことができます。サイドパネル API リファレンスにオプションの完全なリストがあります。

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        askAi: {
          assistantId: 'XXXYYY',
          sidePanel: {
            // @docsearch/sidepanel-js SidepanelProps API をミラー
            panel: {
              variant: 'floating', // または 'inline'
              side: 'right',
              width: '360px',
              expandedWidth: '580px',
              suggestedQuestions: true
            }
          }
        }
      }
    }
  }
})

キーボードショートカットを無効にする必要がある場合は、サイドパネルの keyboardShortcuts オプションを使用してください：

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        askAi: {
          assistantId: 'XXXYYY',
          sidePanel: {
            keyboardShortcuts: {
              'Ctrl/Cmd+I': false
            }
          }
        }
      }
    }
  }
})

モード (auto / sidePanel / hybrid / modal)

VitePress がキーワード検索と Ask AI を統合する方法をオプションで制御できます：

mode: 'auto'（デフォルト）：キーワード検索が設定されている場合は hybrid を推論し、それ以外の場合は Ask AI サイドパネルが設定されている場合は sidePanel を推論します。
mode: 'sidePanel'：サイドパネルのみを強制（キーワード検索ボタンを非表示）。
mode: 'hybrid'：キーワード検索モーダル + Ask AI サイドパネルを有効化（キーワード検索設定が必要）。
mode: 'modal'：Ask AI を DocSearch モーダル内に保持（サイドパネルを設定した場合でも）。

Ask AI のみ（キーワード検索なし）

Ask AI サイドパネルのみを使用する場合は、トップレベルのキーワード検索設定を省略し、askAi の下に認証情報を提供できます：

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        mode: 'sidePanel',
        askAi: {
          assistantId: 'XXXYYY',
          appId: '...',
          apiKey: '...',
          indexName: '...',
          sidePanel: true
        }
      }
    }
  }
})

クローラー設定

このサイトで使用している設定を元にした例です。

<<< @/snippets/algolia-crawler.js

10 KiB Raw Blame History Unescape Escape

検索

ローカル検索

i18n

miniSearch のオプション

コンテンツレンダラーのカスタマイズ

例: 検索対象からページを除外する

例: コンテンツの変換 — 見出しアンカーを追加

Algolia 検索

i18n

Algolia Ask AI のサポート

Ask AI サイドパネル

モード (auto / sidePanel / hybrid / modal)

Ask AI のみ（キーワード検索なし）

クローラー設定

10 KiB

Raw Blame History Unescape Escape