Skip to content

Commit ad2782e

Browse files
committed
fix(website): improve DocSearch relevance and crawler compatibility
1 parent fb932e9 commit ad2782e

2 files changed

Lines changed: 107 additions & 32 deletions

File tree

‎website/docsearch.config.js‎

Lines changed: 101 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -28,18 +28,24 @@ const recordExtractor = ({ $, helpers, url }) => {
2828
// items. Copy code blocks into crawler-only paragraphs so experienced
2929
// users can search for exact Taskfile keys and command syntax without
3030
// changing the page rendered to readers.
31-
$('.vp-doc pre code').each((_, element) => {
32-
const code = $(element).text().trim();
31+
// The crawler editor types $ as accepting strings only. Use eq() to
32+
// access selected nodes without passing a Cheerio Element back to $.
33+
const codeBlocks = $('.vp-doc pre code');
34+
codeBlocks.each((index) => {
35+
const block = codeBlocks.eq(index);
36+
const code = block.text().trim();
3337
if (!code) return;
3438
const paragraph = $('<p></p>').addClass('docsearch-code').text(code);
35-
$(element).closest('pre').replaceWith(paragraph);
39+
block.closest('pre').replaceWith(paragraph);
3640
});
3741

3842
// Select each text subtree once. A list item may contain paragraphs and
3943
// nested lists; selecting both parent and child repeats their content.
40-
$('.vp-doc p, .vp-doc li, .vp-doc td, .vp-doc th').each((_, element) => {
41-
if (!$(element).parents('.docsearch-content').length) {
42-
$(element).addClass('docsearch-content');
44+
const contentElements = $('.vp-doc p, .vp-doc li, .vp-doc td, .vp-doc th');
45+
contentElements.each((index) => {
46+
const content = contentElements.eq(index);
47+
if (!content.parents('.docsearch-content').length) {
48+
content.addClass('docsearch-content');
4349
}
4450
});
4551

@@ -49,6 +55,7 @@ const recordExtractor = ({ $, helpers, url }) => {
4955
// Remove this URL inference once the refactored documentation is live
5056
// and every indexed page exposes the DocSearch metadata.
5157
const pathname = url.pathname.replace(/\/+$/, '') || '/';
58+
const isNavigationPage = pathname === '/docs' || pathname === '/docs/guide';
5259
const inferredSection = (() => {
5360
if (pathname === '/docs') return 'Overview';
5461
if (
@@ -72,25 +79,39 @@ const recordExtractor = ({ $, helpers, url }) => {
7279
$('meta[name="docsearch:section"]').attr('content') || inferredSection;
7380
const docType =
7481
$('meta[name="docsearch:doc_type"]').attr('content') ||
75-
({
82+
{
7683
Overview: 'overview',
7784
Reference: 'reference',
7885
Contributing: 'contributing',
7986
Project: 'project',
8087
Guide: 'guide',
8188
'Getting Started': 'guide'
82-
}[section] ??
83-
'guide');
89+
}[section] ||
90+
'guide';
8491

8592
const keywordsByAnchor = new Map();
86-
$('.vp-doc [data-search-keywords]').each((_, element) => {
87-
const heading = $(element);
93+
const keywordHeadings = $('.vp-doc [data-search-keywords]');
94+
keywordHeadings.each((index) => {
95+
const heading = keywordHeadings.eq(index);
8896
keywordsByAnchor.set(
8997
heading.attr('id'),
9098
heading.attr('data-search-keywords')
9199
);
92100
});
93101

102+
// Common task-oriented phrases should lead to their practical guide.
103+
// These aliases also cover deployed pages that don't yet emit them in HTML.
104+
const guideKeywords = {
105+
'/docs/guide/includes': {
106+
'including-other-taskfiles':
107+
'include another taskfile including taskfiles'
108+
},
109+
'/docs/guide/running-tasks': {
110+
'dry-run-mode': 'dry run preview commands'
111+
}
112+
};
113+
const pageKeywords = guideKeywords[pathname] || {};
114+
94115
const records = helpers.docsearch({
95116
recordProps: {
96117
// Not a heading on the page: the section the page belongs to,
@@ -122,7 +143,11 @@ const recordExtractor = ({ $, helpers, url }) => {
122143
},
123144
// Deprecation notices remain findable, but don't outrank the page
124145
// that documents the supported replacement.
125-
pageRank: pathname.startsWith('/docs/deprecations/') ? '-10' : '0'
146+
pageRank: pathname.startsWith('/docs/deprecations/')
147+
? '-10'
148+
: /^\/docs\/experiments(\/|$)/.test(pathname)
149+
? '-5'
150+
: '0'
126151
},
127152
indexHeadings: true,
128153
aggregateContent: true,
@@ -131,10 +156,41 @@ const recordExtractor = ({ $, helpers, url }) => {
131156

132157
// Matching an alternate term should open its exact section. Adding
133158
// page-wide keywords would make every section on the page compete.
134-
return records.map((record) => ({
135-
...record,
136-
keywords: keywordsByAnchor.get(record.anchor) || ''
137-
}));
159+
return records
160+
.filter((record) => {
161+
// Navigation hubs contain summaries of other pages. Keep their page
162+
// title findable without indexing each card or summary as a result.
163+
if (isNavigationPage) return record.type === 'lvl1';
164+
// These headings organize template variables; their child entries
165+
// (ALIAS, CHECKSUM, EXIT_CODE, etc.) remain indexed with breadcrumbs.
166+
return (
167+
pathname !== '/docs/reference/templating' ||
168+
!['task', 'status', 'loop', 'defer'].includes(record.anchor)
169+
);
170+
})
171+
.map((record) => {
172+
// Rank a section by its own title, independently of its heading depth.
173+
// VitePress adds a zero-width space for the heading permalink.
174+
const title =
175+
[
176+
record.hierarchy.lvl6,
177+
record.hierarchy.lvl5,
178+
record.hierarchy.lvl4,
179+
record.hierarchy.lvl3,
180+
record.hierarchy.lvl2,
181+
record.hierarchy.lvl1
182+
].find(Boolean) || '';
183+
return {
184+
...record,
185+
title: title.replace(/\u200b/g, '').trim(),
186+
keywords: [
187+
keywordsByAnchor.get(record.anchor) || '',
188+
pageKeywords[record.anchor] || ''
189+
]
190+
.filter(Boolean)
191+
.join(' ')
192+
};
193+
});
138194
};
139195

140196
const indexSettings = {
@@ -154,32 +210,30 @@ const indexSettings = {
154210
],
155211
attributesToHighlight: ['hierarchy', 'content'],
156212
attributesToSnippet: ['content:10'],
157-
camelCaseAttributes: ['hierarchy', 'content'],
213+
camelCaseAttributes: ['title', 'hierarchy', 'content'],
158214
searchableAttributes: [
159-
'unordered(hierarchy.lvl0)',
160-
'unordered(hierarchy.lvl1)',
161-
'unordered(hierarchy.lvl2)',
162-
'unordered(hierarchy.lvl3)',
163-
'unordered(hierarchy.lvl4)',
164-
'unordered(hierarchy.lvl5)',
165-
'unordered(hierarchy.lvl6)',
215+
// Ordered titles favor a query at the beginning of the section title.
216+
'title',
166217
'unordered(keywords)',
218+
// Breadcrumb headings provide context at the same priority, without
219+
// favoring a page title over a more specific section heading.
220+
'hierarchy.lvl1,hierarchy.lvl2,hierarchy.lvl3,hierarchy.lvl4,hierarchy.lvl5,hierarchy.lvl6',
221+
'unordered(hierarchy.lvl0)',
167222
'content'
168223
],
169224
distinct: true,
170225
attributeForDistinct: 'url',
171-
customRanking: [
172-
'desc(weight.pageRank)',
173-
'desc(weight.level)',
174-
'asc(weight.position)'
175-
],
226+
customRanking: ['desc(weight.level)', 'asc(weight.position)'],
176227
ranking: [
177228
'words',
178229
'filters',
179230
'typo',
231+
// Exact words beat prefixes such as "for" matching "force". Apply
232+
// deprecation penalties before considering the matched attribute.
233+
'exact',
234+
'desc(weight.pageRank)',
180235
'attribute',
181236
'proximity',
182-
'exact',
183237
'custom'
184238
],
185239
highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">',
@@ -188,13 +242,28 @@ const indexSettings = {
188242
minWordSizefor2Typos: 7,
189243
allowTyposOnNumericTokens: false,
190244
minProximity: 1,
191-
ignorePlurals: true,
245+
// The documentation is English. Applying every language's plural rules
246+
// can turn an unfinished query such as "completi" into another word.
247+
queryLanguages: ['en'],
248+
ignorePlurals: ['en'],
249+
// Exact words in a long paragraph or an ancestor's title shouldn't beat
250+
// an exact match in the destination section's own title or keywords.
251+
disableExactOnAttributes: [
252+
'content',
253+
'hierarchy.lvl0',
254+
'hierarchy.lvl1',
255+
'hierarchy.lvl2',
256+
'hierarchy.lvl3',
257+
'hierarchy.lvl4',
258+
'hierarchy.lvl5',
259+
'hierarchy.lvl6'
260+
],
192261
advancedSyntax: true,
193262
attributeCriteriaComputedByMinProximity: true,
194263
removeWordsIfNoResults: 'allOptional',
195264
separatorsToIndex: '_',
196265
paginationLimitedTo: 1000,
197-
exactOnSingleWordQuery: 'attribute',
266+
exactOnSingleWordQuery: 'word',
198267
queryType: 'prefixLast',
199268
snippetEllipsisText: '',
200269
alternativesAsExact: ['ignorePlurals', 'singleWordSynonym']

‎website/scripts/export-docsearch.mjs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,5 +52,11 @@ for (const [name, settings] of Object.entries(config.initialIndexSettings)) {
5252
`${name}.settings.json`,
5353
JSON.stringify(settings, null, 2) + '\n'
5454
);
55+
// Dashboard imports use an export envelope, unlike the settings API.
56+
// Select only Settings when importing this file.
57+
await write(
58+
`${name}.dashboard.json`,
59+
JSON.stringify({ settings, rules: [], synonyms: [] }, null, 2) + '\n'
60+
);
5561
}
5662
console.log('Export only: no changes were sent to Algolia.');

0 commit comments

Comments
 (0)
⌂ 换网址