docs(plugin-docsearch): improve docs, close #241

vuepress · Sep 12, 2024 · 04801e4 · 04801e4
1 parent 9b31875
commit 04801e4
Show file tree

Hide file tree

Showing 3 changed files with 16 additions and 8 deletions.
diff --git a/docs/plugins/search/docsearch.md b/docs/plugins/search/docsearch.md
@@ -368,6 +368,12 @@ Customize DocSearch options.
 
 ::: warning
 
+To support VuePress's routing and other optimizations, the `transformItems`, `hitComponent` `navigator` and `transformSearchClient` options have been configured internally. Overriding them directly may lead to unexpected behavior.
+
+If you need to customize them, you may need to first understand [VuePress's adaptation](https://github.com/vuepress/ecosystem/blob/main/plugins/search/plugin-docsearch/src/client/composables/useDocSearchSlim.ts) and make sure not to break them.
+
+:::
+
 ## Styles
 
 You can customize styles via CSS variables that provided by [@docsearch/css](https://docsearch.algolia.com/docs/styling):

diff --git a/docs/zh/plugins/search/docsearch.md b/docs/zh/plugins/search/docsearch.md
@@ -356,20 +356,23 @@ export default {
 ### defineDocSearchConfig
 
 ```ts
-type DocSearchClientLocaleOptions = Omit<
-  DocSearchProps,
-  'hitComponent' | 'navigator' | 'transformSearchClient'
->
-
-interface DocSearchClientOptions extends DocSearchClientLocaleOptions {
-  locales?: Record<string, DocSearchClientLocaleOptions>
+interface DocSearchClientOptions extends DocSearchProps {
+  locales?: Record<string, DocSearchProps>
 }
 
 const defineDocSearchConfig: (options: DocSearchClientOptions) => void
 ```
 
 自定义 DocSearch 选项。
 
+::: warning
+
+为了支持 VuePress 的路由与其他优化，`transformItems`, `hitComponent` `navigator` 和 `transformSearchClient` 选项已被内部配置。直接覆盖它们可能会导致非预期行为。
+
+如果你需要自定义它们，你可能需要先理解 [VuePress 的适配](https://github.com/vuepress/ecosystem/blob/main/plugins/search/plugin-docsearch/src/client/composables/useDocSearchSlim.ts) 并确保不破坏它们。
+
+:::
+
 ## 样式
 
 你可以通过 [@docsearch/css](https://docsearch.algolia.com/docs/styling) 提供的 CSS 变量来自定义样式：

diff --git a/themes/theme-default/src/client/config.ts b/themes/theme-default/src/client/config.ts
@@ -2,7 +2,6 @@ import { setupDarkMode } from '@theme/useDarkMode'
 import { useScrollPromise } from '@theme/useScrollPromise'
 import { setupSidebarItems } from '@theme/useSidebarItems'
 import { hasGlobalComponent } from '@vuepress/helper/client'
-import { h } from 'vue'
 import { defineClientConfig } from 'vuepress/client'
 import { Badge, CodeGroup, CodeGroupItem } from './components/global/index.js'
 import Layout from './layouts/Layout.vue'