From ad1689df01f3fa43e5780b59630b77786903fbc5 Mon Sep 17 00:00:00 2001 From: Mister-Hope Date: Thu, 5 Jun 2025 18:00:33 +0800 Subject: [PATCH 1/2] docs(plugin-docsearch): add jsdoc and improve docs --- docs/plugins/search/docsearch.md | 94 ++++---------- docs/zh/plugins/search/docsearch.md | 120 ++++++------------ .../src/client/helpers/docsearch.ts | 61 +++++++++ .../src/node/docsearchPlugin.ts | 38 ++++++ .../plugin-docsearch/src/shared/options.ts | 15 +++ 5 files changed, 176 insertions(+), 152 deletions(-) diff --git a/docs/plugins/search/docsearch.md b/docs/plugins/search/docsearch.md index 38d6953550..e11b3aa416 100644 --- a/docs/plugins/search/docsearch.md +++ b/docs/plugins/search/docsearch.md @@ -30,7 +30,7 @@ export default { You need to [submit the URL of your site](https://docsearch.algolia.com/apply/) to join the DocSearch program. The DocSearch team will send [apiKey](#apikey) and [indexName](#indexname) to your email once the index is generated. Then you can configure this plugin to enable DocSearch in VuePress. -Alternatively, you can [run your own crawler](https://docsearch.algolia.com/docs/run-your-own/) to generate the index, and then use your own [appId](#appId), [apiKey](#apikey) and [indexName](#indexname) to configure this plugin. +Alternatively, you can [run your own crawler](https://docsearch.algolia.com/docs/run-your-own/) to generate the index, and then use your own [appId](#appid), [apiKey](#apikey) and [indexName](#indexname) to configure this plugin. ::: details Official crawler config @@ -40,9 +40,9 @@ new Crawler({ apiKey: 'YOUR_API_KEY', rateLimit: 8, startUrls: [ - // These are urls which algolia start to craw - // If your site is divided in to mutiple parts, - // you may want to set mutiple entry links + // These are urls which Algolia starts to crawl + // If your site is divided into multiple parts, + // you may want to set multiple entry links 'https://YOUR_WEBSITE_URL/', ], sitemaps: [ @@ -54,13 +54,13 @@ new Crawler({ // You can use this to stop algolia crawing some paths ], discoveryPatterns: [ - // These are urls which algolia looking for, + // These are urls which Algolia is looking for, 'https://YOUR_WEBSITE_URL/**', ], // Crawler schedule, set it according to your docs update frequency schedule: 'at 02:00 every 1 day', actions: [ - // you may have mutiple actions, especially when you are deploying mutiple docs under one domain + // you may have multiple actions, especially when you are deploying multiple docs under one domain { // name the index with name you like indexName: 'YOUR_INDEX_NAME', @@ -89,7 +89,7 @@ new Crawler({ }, ], initialIndexSettings: { - // controls how index are initialized + // controls how indexes are initialized // only has effects before index are initialize // you may need to delete your index and recraw after modification YOUR_INDEX_NAME: { @@ -174,12 +174,8 @@ If you are not using default theme, or you meet any problems when using docsearc ### apiKey - Type: `string` - -- Required: `true` - -- Details: - - The `apiKey` that you received from the DocSearch team, or generated by yourself. +- Required: Yes +- Details: The `apiKey` that you received from the DocSearch team, or generated by yourself. - Also see: - [DocSearch > Options > apiKey](https://docsearch.algolia.com/docs/api#apikey) @@ -187,12 +183,8 @@ If you are not using default theme, or you meet any problems when using docsearc ### indexName - Type: `string` - -- Required: `true` - -- Details: - - The `indexName` that you received from the DocSearch team, or generated by yourself. +- Required: Yes +- Details: The `indexName` that you received from the DocSearch team, or generated by yourself. - Also see: - [DocSearch > Options > indexName](https://docsearch.algolia.com/docs/api#indexname) @@ -200,12 +192,8 @@ If you are not using default theme, or you meet any problems when using docsearc ### appId - Type: `string` - -- Required: `true` - -- Details: - - It defines your own application ID. +- Required: Yes +- Details: It defines your own application ID. - Also see: - [DocSearch > Options > appId](https://docsearch.algolia.com/docs/api#appid) @@ -213,27 +201,18 @@ If you are not using default theme, or you meet any problems when using docsearc ### searchParameters - Type: `SearchParameters` - -- Details: - - Parameters of Algolia Search API. - -- Also see: +- Reference: - [DocSearch > Options > searchParameters](https://docsearch.algolia.com/docs/api/#searchparameters) - [Algolia > Search API Parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/) +- Details: Parameters of Algolia Search API. ### placeholder - Type: `string` - - Default: `'Search docs'` - -- Details: - - The placeholder attribute of the search input. - -- Also see: +- Reference: - [DocSearch > Options > placeholder](https://docsearch.algolia.com/docs/api/#placeholder) +- Details: The placeholder attribute of the search input. ### disableUserPersonalization @@ -245,29 +224,22 @@ If you are not using default theme, or you meet any problems when using docsearc Whether to disable all personalized features: recent searches, favorite searches, etc. -- Also see: +- Reference: - [DocSearch > Options > disableUserPersonalization](https://docsearch.algolia.com/docs/api/#disableuserpersonalization) ### initialQuery - Type: `string` +- Details: The initial query when the modal opens. -- Details: - - The initial query when the modal opens. - -- Also see: +- Reference: - [DocSearch > Options > initialQuery](https://docsearch.algolia.com/docs/api/#initialquery) ### maxResultsPerGroup - Type: `number` - - Default: `5` - -- Details: - - The maximum number of results per group. +- Details: The maximum number of results per group. - Also see: - [DocSearch > Options > maxResultsPerGroup](https://docsearch.algolia.com/docs/api/#maxresultspergroup) @@ -275,10 +247,7 @@ If you are not using default theme, or you meet any problems when using docsearc ### translations - Type: `Partial` - -- Details: - - Allow replacing the default text in the DocSearch button or modal. +- Details: Allow replacing the default text in the DocSearch button or modal. - Also see: - [DocSearch > Options > translations](https://docsearch.algolia.com/docs/api/#translations) @@ -286,12 +255,7 @@ If you are not using default theme, or you meet any problems when using docsearc ### locales - Type: `Record` - -- Details: - - Options of this plugin in different locales. - - All other options of this plugin are acceptable in locale config. +- Details: Options of this plugin in different locales. All other options of this plugin are acceptable in locale config. - Example: @@ -331,12 +295,8 @@ export default { ### indexBase - Type: `string` - - Default: [base](https://vuejs.press/reference/config.html#base) - -- Details: - - The base path of the search index. +- Details: The base path of the search index. If you are deploying your site to multiple domains, you don't need to submit all of them to DocSearch and generate search index separately. You could choose one of the domains as the _index domain_, and only submit the _index domain_ to DocSearch for crawling search index. Then, you could reuse the search index across all deployments. @@ -345,12 +305,8 @@ export default { ### injectStyles - Type: `boolean` - - Default: `true` - -- Details: - - Whether to inject the default styles of DocSearch or not. +- Details: Whether to inject the default styles of DocSearch or not. If you think the default styles of DocSearch is not compatible with your site, you can try to override the default styles, or set this option to `false` to totally exclude the default styles. diff --git a/docs/zh/plugins/search/docsearch.md b/docs/zh/plugins/search/docsearch.md index 340f89c7cc..401e1d4c81 100644 --- a/docs/zh/plugins/search/docsearch.md +++ b/docs/zh/plugins/search/docsearch.md @@ -30,7 +30,7 @@ export default { 你需要 [提交你的网站 URL](https://docsearch.algolia.com/apply/) 来加入 DocSearch 项目。当你的索引成功创建后， DocSearch 团队会将 [apiKey](#apikey) 和 [indexName](#indexname) 发送到你的邮箱。接下来，你就可以配置该插件，在 VuePress 中启用 DocSearch 了。 -或者，你也可以 [运行你自己的爬虫](https://docsearch.algolia.com/docs/run-your-own/) 来创建索引，然后使用你自己的 [appId](#appId), [apiKey](#apikey) 和 [indexName](#indexname) 来配置该插件。 +或者，你也可以 [运行你自己的爬虫](https://docsearch.algolia.com/docs/run-your-own/) 来创建索引，然后使用你自己的 [appId](#appid), [apiKey](#apikey) 和 [indexName](#indexname) 来配置该插件。 ::: details 官方爬虫配置示例 @@ -41,7 +41,7 @@ new Crawler({ rateLimit: 8, startUrls: [ // 这是 Algolia 开始抓取网站的初始地址 - // 如果你的网站被分为数个独立部分，你可能需要在此设置多个入口链接 + // 如果你的网站被分为多个独立部分，你可能需要在此设置多个入口链接 'https://YOUR_WEBSITE_URL/', ], sitemaps: [ @@ -59,7 +59,7 @@ new Crawler({ // 爬虫执行的计划时间，可根据文档更新频率设置 schedule: 'at 02:00 every 1 day', actions: [ - // 你可以拥有多个 action，特别是你在一个域名下部署多个文档时 + // 你可以拥有多个 action，特别是当你在一个域名下部署多个文档时 { // 使用适当的名称为索引命名 indexName: 'YOUR_INDEX_NAME', @@ -172,50 +172,35 @@ new Crawler({ ### apiKey -- 类型： `string` - -- 是否必需： `true` - -- 详情： - - 从 DocSearch 团队收到的 `apiKey` ，或者由你自己生成。 +- 类型：`string` +- 必填：是 +- 详情：从 DocSearch 团队收到的 `apiKey` ，或者由你自己生成。 - 参考： - [DocSearch > Options > apiKey](https://docsearch.algolia.com/docs/api#apikey) ### indexName -- 类型： `string` - -- 是否必需： `true` - -- 详情： - - 从 DocSearch 团队收到的 `indexName` ，或者由你自己生成。 +- 类型：`string` +- 必填：是 +- 详情：从 DocSearch 团队收到的 `indexName` ，或者由你自己生成。 - 参考： - [DocSearch > Options > indexName](https://docsearch.algolia.com/docs/api#indexname) ### appId -- 类型： `string` - -- 是否必需： `true` - -- 详情： - - 用于设置你的 Application ID。 +- 类型：`string` +- 必填：是 +- 详情：用于设置你的 Application ID。 - 参考： - [DocSearch > Options > appId](https://docsearch.algolia.com/docs/api#appid) ### searchParameters -- 类型： `SearchParameters` - -- 详情： - - Algolia 搜索 API 参数。 +- 类型：`SearchParameters` +- 详情：Algolia 搜索 API 参数。 - 参考： - [DocSearch > Options > searchParameters](https://docsearch.algolia.com/docs/api/#searchparameters) @@ -223,74 +208,51 @@ new Crawler({ ### placeholder -- 类型： `string` - -- 默认值： `'Search docs'` - -- 详情： - - 搜索输入框的 placeholder 属性。 +- 类型：`string` +- 默认值：`'Search docs'` +- 详情：搜索输入框的 placeholder 属性。 - 参考： - [DocSearch > Options > placeholder](https://docsearch.algolia.com/docs/api#placeholder) ### disableUserPersonalization -- 类型： `boolean` - -- 默认值： `false` - -- 详情： - - 是否禁用所有的个性化功能：最近的搜索、收藏的搜索结果等。 +- 类型：`boolean` +- 默认值：`false` +- 详情：是否禁用所有的个性化功能：最近的搜索、收藏的搜索结果等。 - 参考： - [DocSearch > Options > disableUserPersonalization](https://docsearch.algolia.com/docs/api#disableuserpersonalization) ### initialQuery -- 类型： `string` - -- 详情： - - 打开弹窗时的初始请求。 +- 类型：`string` +- 详情：打开弹窗时的初始请求。 - 参考： - [DocSearch > Options > initialQuery](https://docsearch.algolia.com/docs/api#initialquery) ### translations -- 类型： `Partial` - -- 详情： - - 允许替换 DocSearch 按钮和弹窗内的默认文字。 +- 类型：`Partial` +- 详情：允许替换 DocSearch 按钮和弹窗内的默认文字。 - 参考： - [DocSearch > Options > translations](https://docsearch.algolia.com/docs/api/#translations) ### maxResultsPerGroup -- 类型： `number` - -- 默认值： `5` - -- 详情： - - 每个组的最大结果数。 +- 类型：`number` +- 默认值：`5` +- 详情：每个组的最大结果数。 - 参考： - [DocSearch > Options > maxResultsPerGroup](https://docsearch.algolia.com/docs/api#maxresultspergroup) ### locales -- 类型： `Record` - -- 详情： - - 在不同 locales 下对该插件进行不同的配置。 - - 该插件的所有其他选项都可以在 locale 中进行配置。 +- 类型：`Record` +- 详情：在不同 locales 下对该插件进行不同的配置。该插件的所有其他选项都可以在 locale 中进行配置。 - 示例： @@ -329,27 +291,19 @@ export default { ### indexBase -- 类型： `string` - -- 默认值： [base](https://vuejs.press/zh/reference/config.html#base) - -- 详情： +- 类型：`string` +- 默认值：[base](https://vuejs.press/zh/reference/config.html#base) +- 详情：搜索索引基础路径。 - 搜索索引基础路径。 - - 如果你需要把你的站点部署到不同的域名上，你不需要把它们全都提交到 DocSearch 上来分别生成搜索索引。你可以选择其中一个域名作为 _索引域名_ ，并且仅将 _索引域名_ 提交到 DocSearch 上来爬去搜索索引。然后，你就可以在不同的部署域名下复用索引。 + 如果你需要把你的站点部署到不同的域名上，你不需要把它们全都提交到 DocSearch 上来分别生成搜索索引。你可以选择其中一个域名作为 _索引域名_ ，并且仅将 _索引域名_ 提交到 DocSearch 上来爬取搜索索引。然后，你就可以在不同的部署域名下复用索引。 如果你不同部署域名下的 [base](https://vuejs.press/zh/reference/config.html#base) 是不一样的，你就需要将这个配置设置成 _索引域名_ 的 [base](https://vuejs.press/zh/reference/config.html#base) ，这样其他的部署域名就可以正确复用索引了。 ### injectStyles -- 类型： `boolean` - -- 默认值： `true` - -- 详情： - - 是否注入 DocSearch 的默认样式。 +- 类型：`boolean` +- 默认值：`true` +- 详情：是否注入 DocSearch 的默认样式。 如果你认为 DocSearch 的默认样式和你的站点不兼容，你可以尝试覆盖默认样式，或者将该选项设置为 `false` 来完全移除默认样式。 @@ -371,7 +325,7 @@ const defineDocSearchConfig: ( ) => void ``` -自定义 DocSearch 选项，支持普通对象，Ref 者 Getter。 +自定义 DocSearch 选项，支持普通对象，Ref 或 Getter。 ::: warning diff --git a/plugins/search/plugin-docsearch/src/client/helpers/docsearch.ts b/plugins/search/plugin-docsearch/src/client/helpers/docsearch.ts index cf5bdc037b..6696d0956d 100644 --- a/plugins/search/plugin-docsearch/src/client/helpers/docsearch.ts +++ b/plugins/search/plugin-docsearch/src/client/helpers/docsearch.ts @@ -26,12 +26,67 @@ const docsearchSymbol: InjectionKey> = Symbol( __VUEPRESS_DEV__ ? 'docsearch' : '', ) +/** + * DocSearch client locale options + * + * DocSearch 客户端多语言选项 + */ export type DocSearchClientLocaleOptions = Partial +/** + * DocSearch client options + * + * DocSearch 客户端选项 + */ export interface DocSearchClientOptions extends DocSearchClientLocaleOptions { + /** + * Locale options + * + * 多语言选项 + */ locales?: Record } +/** + * Customize DocSearch options + * + * 自定义 DocSearch 选项 + * + * @param options - DocSearch options, support plain object, ref or getter / DocSearch 选项，支持普通对象，Ref 或 Getter + * + * @example + * ```ts + * import { defineDocSearchConfig } from '@vuepress/plugin-docsearch/client' + * + * // Use plain object + * defineDocSearchConfig({ + * translations: { + * button: { + * buttonText: 'Search', + * }, + * }, + * }) + * + * // Use ref + * const options = ref({ + * translations: { + * button: { + * buttonText: 'Search', + * }, + * }, + * }) + * defineDocSearchConfig(options) + * + * // Use getter + * defineDocSearchConfig(() => ({ + * translations: { + * button: { + * buttonText: isDarkMode.value ? 'Search in dark' : 'Search in light', + * }, + * }, + * })) + * ``` + */ export const defineDocSearchConfig = ( options: MaybeRefOrGetter, ): void => { @@ -51,6 +106,9 @@ export const defineDocSearchConfig = ( } } +/** + * @internal + */ export const useDocSearchOptions = (): ComputedRef => { const options = inject(docsearchSymbol)! const routeLocale = useRouteLocale() @@ -61,6 +119,9 @@ export const useDocSearchOptions = (): ComputedRef => { })) } +/** + * @internal + */ export const injectDocSearchConfig = (app: App): void => { // @ts-expect-error: Types loop back app.provide(docsearchSymbol, readonly(docsearchOptions)) diff --git a/plugins/search/plugin-docsearch/src/node/docsearchPlugin.ts b/plugins/search/plugin-docsearch/src/node/docsearchPlugin.ts index 22d38766c2..9ef26c2de0 100644 --- a/plugins/search/plugin-docsearch/src/node/docsearchPlugin.ts +++ b/plugins/search/plugin-docsearch/src/node/docsearchPlugin.ts @@ -7,19 +7,57 @@ import { PLUGIN_NAME } from './utils.js' /** * Options for @vuepress/plugin-docsearch + * + * @vuepress/plugin-docsearch 的配置项 */ export interface DocSearchPluginOptions extends DocSearchOptions { /** * Base path of the search index + * + * 搜索索引的基础路径 */ indexBase?: string /** * Whether to inject docsearch default styles + * + * 是否注入 docsearch 的默认样式 + * + * @default true */ injectStyles?: boolean } +/** + * DocSearch plugin + * + * DocSearch 插件 + * + * @param options - DocSearch plugin options / DocSearch 插件选项 + * + * @example + * ```ts + * import { docsearchPlugin } from '@vuepress/plugin-docsearch' + * + * export default { + * plugins: [ + * docsearchPlugin({ + * appId: 'XXXXXX', + * apiKey: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', + * indexName: 'xxxxxxxx', + * locales: { + * '/': { + * placeholder: 'Search Documentation', + * }, + * '/zh/': { + * placeholder: '搜索文档', + * }, + * }, + * }), + * ], + * } + * ``` + */ export const docsearchPlugin = ({ injectStyles = true, indexBase, diff --git a/plugins/search/plugin-docsearch/src/shared/options.ts b/plugins/search/plugin-docsearch/src/shared/options.ts index 3cef9764b6..86f31e225b 100644 --- a/plugins/search/plugin-docsearch/src/shared/options.ts +++ b/plugins/search/plugin-docsearch/src/shared/options.ts @@ -1,6 +1,11 @@ import type { DocSearchProps } from '@docsearch/react' import type { LocaleConfig } from 'vuepress/shared' +/** + * DocSearch locale options + * + * DocSearch 多语言选项 + */ export type DocSearchLocaleOptions = Partial< Pick< DocSearchProps, @@ -16,6 +21,16 @@ export type DocSearchLocaleOptions = Partial< > > +/** + * DocSearch options + * + * DocSearch 选项 + */ export interface DocSearchOptions extends DocSearchLocaleOptions { + /** + * Locale options + * + * 多语言选项 + */ locales?: LocaleConfig } From 88ed6773af24cf3c14e3694d8055193259aac35a Mon Sep 17 00:00:00 2001 From: Mister-Hope Date: Thu, 5 Jun 2025 18:05:33 +0800 Subject: [PATCH 2/2] chore: tweaks --- docs/plugins/search/docsearch.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/plugins/search/docsearch.md b/docs/plugins/search/docsearch.md index e11b3aa416..d6333687e5 100644 --- a/docs/plugins/search/docsearch.md +++ b/docs/plugins/search/docsearch.md @@ -201,28 +201,26 @@ If you are not using default theme, or you meet any problems when using docsearc ### searchParameters - Type: `SearchParameters` +- Details: Algolia Search API parameters. + - Reference: - [DocSearch > Options > searchParameters](https://docsearch.algolia.com/docs/api/#searchparameters) - [Algolia > Search API Parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/) -- Details: Parameters of Algolia Search API. ### placeholder - Type: `string` - Default: `'Search docs'` +- Details: The placeholder attribute of the search input. + - Reference: - [DocSearch > Options > placeholder](https://docsearch.algolia.com/docs/api/#placeholder) -- Details: The placeholder attribute of the search input. ### disableUserPersonalization - Type: `boolean` - - Default: `false` - -- Details: - - Whether to disable all personalized features: recent searches, favorite searches, etc. +- Details: Whether to disable all personalized features: recent searches, favorite searches, etc. - Reference: - [DocSearch > Options > disableUserPersonalization](https://docsearch.algolia.com/docs/api/#disableuserpersonalization)