Content Search
Overview
The theme provides two approaches for content search:
- Local Content Search
- Algolia DocSearch
Note: Do not configure both approaches simultaneously. The precedence is: top-level search > plugins.docsearch > local search.
In other words, when plugins.docsearch and plugins.search are both configured, Algolia DocSearch takes effect.
For configuration options, please refer to Configuration > Content Search.
Local Content Search
Local Content Search is powered by the @vuepress-plume/plugin-search plugin.
This plugin uses minisearch for content searching.
Enabling
The theme enables Local Content Search by default. You can also customize its configuration.
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
search: {
provider: 'local',
// more options
}
})
})This plugin generates search indexes locally based on your pages, then loads the search index files when users open the search box for the first time. In other words, this is a lightweight built-in search capability that doesn't make any external requests.
When an index is large, the plugin automatically splits it into multiple shards per locale. The client loads them on demand and parses one shard at a time, so a single huge index file never blocks rendering for long.
However, when your site contains a large number of pages, the search index can still become very large, and sharding adds extra requests and loading time. In such cases, we recommend using a more robust solution - Algolia DocSearch.
Algolia DocSearch
Site content search powered by Algolia DocSearch.
Enabling
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
search: {
provider: 'algolia',
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_API_KEY',
indexName: 'YOUR_INDEX_NAME',
},
}),
})Without appId and apiKey, there will be no search box
When provider is 'algolia', appId and apiKey must both be present. If either is missing, the theme will only output a console.error line at build time and will not register any search plugin.
Obtaining Search Index
You need to submit your website URL to join the DocSearch program. When your index is successfully created, the DocSearch team will send apiKey and indexName to your email. You can then configure the plugin to enable DocSearch in VuePress.
Alternatively, you can run your own crawler to create the index, then use your own appId, apiKey, and indexName to configure the plugin.
Here's a crawler configuration example used by this theme. You can visit Algolia Crawler and modify it according to your needs:
new Crawler({
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_API_KEY',
rateLimit: 8,
startUrls: [
// These are the initial URLs where Algolia starts crawling your site
// If your site is divided into several independent sections, you may need to set multiple entry links here
'https://YOUR_WEBSITE_URL/',
],
renderJavaScript: false,
sitemaps: [
// The theme generates sitemap by default; replace with your domain link here
'https://YOUR_WEBSITE_URL/sitemap.xml',
],
ignoreCanonicalTo: true,
discoveryPatterns: [
// This defines the scope of URLs that Algolia will crawl
'https://YOUR_WEBSITE_URL/**',
],
// Crawler execution schedule; set according to your documentation update frequency
schedule: 'at 02:00 every 1 day',
actions: [
// You can have multiple actions, especially when deploying multiple documentations under one domain
{
// Name your index appropriately
indexName: 'YOUR_INDEX_NAME',
// Paths where the index takes effect
pathsToMatch: ['https://YOUR_WEBSITE_URL/**'],
recordExtractor: ({ helpers }) => {
// Options for vuepress-theme-plume
return helpers.docsearch({
recordProps: {
lvl1: '.plume-content h1',
content: '.plume-content p, .plume-content li',
lvl0: {
selectors: [
'.sidebar-item.is-active p',
'.content-container .page-title',
],
defaultValue: 'Documentation',
},
lvl2: '.plume-content h2',
lvl3: '.plume-content h3',
lvl4: '.plume-content h4',
lvl5: '.plume-content h5',
},
indexHeadings: true,
aggregateContent: true,
recordVersion: 'v3',
})
},
},
],
initialIndexSettings: {
// Controls how the index is initialized; only effective when the index hasn't been generated yet
// You may need to manually delete and regenerate the index after modifications
YOUR_INDEX_NAME: {
attributesForFaceting: ['type', 'lang'],
attributesToRetrieve: [
'hierarchy',
'content',
'anchor',
'url',
'url_without_anchor',
'type',
],
attributesToHighlight: ['hierarchy', 'hierarchy_camel', 'content'],
attributesToSnippet: ['content:10'],
camelCaseAttributes: ['hierarchy', 'hierarchy_radio', 'content'],
searchableAttributes: [
'unordered(hierarchy_radio_camel.lvl0)',
'unordered(hierarchy_radio.lvl0)',
'unordered(hierarchy_radio_camel.lvl1)',
'unordered(hierarchy_radio.lvl1)',
'unordered(hierarchy_radio_camel.lvl2)',
'unordered(hierarchy_radio.lvl2)',
'unordered(hierarchy_radio_camel.lvl3)',
'unordered(hierarchy_radio.lvl3)',
'unordered(hierarchy_radio_camel.lvl4)',
'unordered(hierarchy_radio.lvl4)',
'unordered(hierarchy_radio_camel.lvl5)',
'unordered(hierarchy_radio.lvl5)',
'unordered(hierarchy_radio_camel.lvl6)',
'unordered(hierarchy_radio.lvl6)',
'unordered(hierarchy_camel.lvl0)',
'unordered(hierarchy.lvl0)',
'unordered(hierarchy_camel.lvl1)',
'unordered(hierarchy.lvl1)',
'unordered(hierarchy_camel.lvl2)',
'unordered(hierarchy.lvl2)',
'unordered(hierarchy_camel.lvl3)',
'unordered(hierarchy.lvl3)',
'unordered(hierarchy_camel.lvl4)',
'unordered(hierarchy.lvl4)',
'unordered(hierarchy_camel.lvl5)',
'unordered(hierarchy.lvl5)',
'unordered(hierarchy_camel.lvl6)',
'unordered(hierarchy.lvl6)',
'content',
],
distinct: true,
attributeForDistinct: 'url',
customRanking: [
'desc(weight.pageRank)',
'desc(weight.level)',
'asc(weight.position)',
],
ranking: [
'words',
'filters',
'typo',
'attribute',
'proximity',
'exact',
'custom',
],
highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">',
highlightPostTag: '</span>',
minWordSizefor1Typo: 3,
minWordSizefor2Typos: 7,
allowTyposOnNumericTokens: false,
minProximity: 1,
ignorePlurals: true,
advancedSyntax: true,
attributeCriteriaComputedByMinProximity: true,
removeWordsIfNoResults: 'allOptional',
},
},
})The recordProps section contains configuration options used by this theme for index crawling.
Configuration Options
For complete configuration, please refer to the documentation.
Configuration Example
Here's the configuration used by this theme:
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
search: {
provider: 'algolia',
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_API_KEY',
indexName: 'YOUR_INDEX_NAME',
}
})
})