Skip to content

RUN-5040: Fix docsearch config: use indices instead of indexName #1987

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
ltamaster merged 2 commits into from
Oct 2, 2026
Merged

RUN-5040: Fix docsearch config: use indices instead of indexName #1987

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
77412c9
[RUN-5040] Fix docsearch config: use indices instead of indexName
ltamaster Oct 2, 2026
a5a1af1
[RUN-5040] Update DocSearch docs to show indices wrapper
ltamaster Oct 2, 2026
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
17 changes: 12 additions & 5 deletions .claude/docs/docsearch-filters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,13 +63,20 @@ To add new sections:
### VuePress Configuration
The DocSearch configuration in `docs/.vuepress/config.ts` includes:
```typescript
searchParameters: {
hitsPerPage: 100,
facetFilters: [`version:${setup.base}`],
facets: ['tags']
}
indices: [
{
name: 'prod_rundeck_docs',
searchParameters: {
hitsPerPage: 100,
facetFilters: [`version:${setup.base}`],
facets: ['tags']
},
},
],
```

`@vuepress/plugin-docsearch` rc.134+ requires `indices`. Do not use the legacy root-level `indexName` / `searchParameters`: `indices` ends up undefined and clicking Search throws `TypeError: Cannot read properties of undefined (reading 'map')`.

The `facets: ['tags']` tells Algolia to include tags as filterable attributes.

## Styling
Expand Down
6 changes: 3 additions & 3 deletions .claude/docs/writing-style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Search is powered by Algolia DocSearch via `@vuepress/plugin-docsearch`.
| Index name | `prod_rundeck_docs` |
| Scraper | `algolia/docsearch-scraper` Docker image, driven by CircleCI |
| Scraper config | `.docsearch/config.json` (selectors, start URLs, faceting attributes) |
| VuePress plugin config | `docs/.vuepress/config.ts` (`appId`, `apiKey`, `searchParameters`) |
| VuePress plugin config | `docs/.vuepress/config.ts` (`appId`, `apiKey`, `indices[].searchParameters`) |
| Current facets | `version` (e.g. `docs`, `4.0.x`), `lang` |
| Section tags | Applied via URL patterns in `start_urls` (Learning, User Guide, API, Administration, Developer, Release Notes, General) |

Expand All @@ -52,8 +52,8 @@ The custom section-filter UI is documented in `.claude/docs/docsearch-filters.md
### When Search Won't Update

- After adding new `start_urls` with tags to `.docsearch/config.json`, re-scrape the index — existing records carry stale tags until re-indexed.
- `searchParameters.facetFilters` in `docs/.vuepress/config.ts` MUST include `version:${setup.base}` so results scope correctly to the current version.
- `searchParameters.facets` MUST include `'tags'` for the filter UI to work.
- `indices[].searchParameters.facetFilters` in `docs/.vuepress/config.ts` MUST include `version:${setup.base}` so results scope correctly to the current version.
- `indices[].searchParameters.facets` MUST include `'tags'` for the filter UI to work.

## Content Directory Structure

Expand Down
16 changes: 10 additions & 6 deletions docs/.vuepress/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,13 +128,17 @@ export default defineUserConfig({
docsearch: {
appId: 'GRSXNRCDRG',
apiKey: 'c463f74d6f36a5af808650e0f69aadfa',
indexName: 'prod_rundeck_docs',
indices: [
{
name: 'prod_rundeck_docs',
searchParameters: {
hitsPerPage: 100,
facetFilters: [`version:${setup.base}`],
facets: ['tags']
},
Comment on lines +134 to +138

@ltamaster ltamaster Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Good catch, updated .claude/docs/docsearch-filters.md to show the indices wrapper (with a note about the rc.134 requirement), and also fixed the searchParameters references in .claude/docs/writing-style.md. Pushed in a5a1af1.

},
],
maxResultsPerGroup: 20,
searchParameters: {
hitsPerPage: 100,
facetFilters: [`version:${setup.base}`],
facets: ['tags']
},
locales: {
'/': {
placeholder: 'Search Documentation',
Expand Down
Loading