Skip to content

Add clientOptionsModule option to DocSearch plugin - #2822

Merged
delucis merged 9 commits into
withastro:mainfrom
KianNH:kian/docsearch-options-module
Jan 28, 2025
Merged

delucis merged 9 commits into
withastro:mainfrom
KianNH:kian/docsearch-options-module

Conversation

@KianNH

@KianNH KianNH commented Jan 22, 2025

Copy link
Copy Markdown
Contributor

Description

  • Closes DocSearch component supports custom link for results footer component #2806
  • Adds a clientOptionsModule option to the starlightDocSearch plugin.
    • This takes the shape of a path to a JavaScript or TypeScript file which will be imported (if present) and merged with existing options in the starlight/docsearch-config virtual module.
    • If an option exists in both, i.e appId, the option in the clientOptionsModule file will be used.

Considerations

  • Updating documentation

#### DocSearch configuration
The Starlight DocSearch plugin also supports customizing the DocSearch component with the following additional options:
- `maxResultsPerGroup`: Limit the number of results displayed for each search group. Default is `5`.
- `disableUserPersonalization`: Prevent DocSearch from saving a user’s recent searches and favorites to local storage. Default is `false`.
- `insights`: Enable the Algolia Insights plugin and send search events to your DocSearch index. Default is `false`.
- `searchParameters`: An object customizing the [Algolia Search Parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/).

  • Tests

Whilst this is probably not a large enough package to warrant it, I did setup try out setting up Vitest for this package where vitePluginDocSearch is passed in vitest.config.ts but since it would need a lot of work to setup a harness to test starlightDocSearch I opted against including it.

@changeset-bot

changeset-bot Bot commented Jan 22, 2025 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: cd7af21

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@astrojs/starlight-docsearch Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions github-actions Bot added the 🌟 docsearch Changes to Starlight’s DocSearch plugin label Jan 22, 2025
@netlify

netlify Bot commented Jan 22, 2025 •

Copy link
Copy Markdown

✅ Deploy Preview for astro-starlight ready!

Name Link
🔨 Latest commit cd7af21
🔍 Latest deploy log https://app.netlify.com/sites/astro-starlight/deploys/6798d7ae97312a000877ceba
😎 Deploy Preview https://deploy-preview-2822--astro-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 100
Accessibility: 100
Best Practices: 100
SEO: 100
PWA: -
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

@HiDeoo HiDeoo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a complete review or request for some changes, but I left a few comments mostly regarding the JSDoc to start some discussion around the approach.

One other question coming to mind is if we should expose a defineDocSearchConfig helper just for the typings or something similar?

Comment thread packages/docsearch/index.ts Resolved
Comment thread packages/docsearch/index.ts Resolved
Comment thread packages/docsearch/index.ts Outdated
*/
searchParameters: z.custom<SearchOptions>(),
/**
* A JavaScript module containing a default export. These options

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should specify what the default export should be.

@delucis delucis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good @KianNH! Seconding @HiDeoo’s idea to make the option module all-or-nothing, so if you use that, you move all config there, unless there’s a reason not to do that anyone can see.

I also agree we should export something to help with typing the options module. Given this module will end up in client-side code, I might suggest just a type rather than a defineClientOptions() utility just to avoid the extra no-op function in the bundle. (Would also allow us to export it directly from @astrojs/starlight-docsearch rather than needing a dedicated file just for that.) That would help us assert that e.g. you shouldn’t set the container property which Starlight takes care of.

So something like:

import type docsearch from '@docsearch/js';

export type DocSearchClientOptions = Omit<Parameters<typeof docsearch>[0], 'container'>;

And then users can write config as:

import type { DocSearchClientOptions } from '@astrojs/starlight-docsearch';

export default { 
  // ...
} satisfies DocSearchClientOptions;

@github-actions github-actions Bot added the 📚 docs Documentation website changes label Jan 28, 2025
@astrobot-houston

astrobot-houston commented Jan 28, 2025 •

Copy link
Copy Markdown
Contributor

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale File Note
en guides/site-search.mdx Source changed, localizations will be marked as outdated.
Warnings reference
Icon Description
🔄️ The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

delucis and others added 2 commits January 28, 2025 12:37
Co-Authored-By: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

@delucis delucis left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks again for this @KianNH! I took the liberty of adding some docs and I’ll get it released 🙌

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

📚 docs Documentation website changes 🌟 docsearch Changes to Starlight’s DocSearch plugin

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants