Skip to content

docs(plugin-docsearch): add jsdoc and improve docs #533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 5, 2025
Merged

docs(plugin-docsearch): add jsdoc and improve docs #533

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ad1689d
docs(plugin-docsearch): add jsdoc and improve docs
Mister-Hope Jun 5, 2025
88ed677
chore: tweaks
Mister-Hope Jun 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 26 additions & 72 deletions docs/plugins/search/docsearch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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: [
Expand All @@ -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',
Expand Down Expand Up @@ -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: {
Expand Down Expand Up @@ -174,124 +174,86 @@ 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)

### 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)

### 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)

### searchParameters

- Type: `SearchParameters`
- Details: Algolia Search API parameters.

- 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/)

### placeholder

- Type: `string`

- Default: `'Search docs'`
- Details: The placeholder attribute of the search input.

- Details:

The placeholder attribute of the search input.

- Also see:
- Reference:
- [DocSearch > Options > placeholder](https://docsearch.algolia.com/docs/api/#placeholder)

### 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.

- 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)

### translations

- Type: `Partial<DocSearchTranslations>`

- 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)

### locales

- Type: `Record<string, DocSearchPluginOptions>`

- 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:

Expand Down Expand Up @@ -331,12 +293,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.

Expand All @@ -345,12 +303,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.

Expand Down
Loading
Loading