搜索

本地搜索

得益于 minisearch，VitePress 支持使用浏览器内索引进行模糊全文搜索。要启用此功能，只需在 .vitepress/config.ts 文件中将 themeConfig.search.provider 选项设置为 'local' 即可：

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
		},
	},
})

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
		},
	},
})

示例结果：

或者，你可以使用 Algolia DocSearch 或一些社区插件，例如：https://www.npmjs.com/package/vitepress-plugin-search 或者 https://www.npmjs.com/package/vitepress-plugin-pagefind。

i18n

你可以使用这样的配置来使用多语言搜索：

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
			options: {
				locales: {
					zh: {
						translations: {
							button: {
								buttonText: '搜索文档',
								buttonAriaLabel: '搜索文档',
							},
							modal: {
								noResultsText: '无法找到相关结果',
								resetButtonTitle: '清除查询条件',
								footer: {
									selectText: '选择',
									navigateText: '切换',
								},
							},
						},
					},
				},
			},
		},
	},
})

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
			options: {
				locales: {
					zh: {
						translations: {
							button: {
								buttonText: '搜索文档',
								buttonAriaLabel: '搜索文档',
							},
							modal: {
								noResultsText: '无法找到相关结果',
								resetButtonTitle: '清除查询条件',
								footer: {
									selectText: '选择',
									navigateText: '切换',
								},
							},
						},
					},
				},
			},
		},
	},
})

MiniSearch 配置项

你可以像这样配置 MiniSearch ：

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
			options: {
				miniSearch: {
					/**
					 * @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
					 */
					options: {
						/* ... */
					},
					/**
					 * @type {import('minisearch').SearchOptions}
					 * @default
					 * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
					 */
					searchOptions: {
						/* ... */
					},
				},
			},
		},
	},
})

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
			options: {
				miniSearch: {
					/**
					 * @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
					 */
					options: {
						/* ... */
					},
					/**
					 * @type {import('minisearch').SearchOptions}
					 * @default
					 * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
					 */
					searchOptions: {
						/* ... */
					},
				},
			},
		},
	},
})

在 MiniSearch docs了解更多信息。

自定义渲染内容

你可以在索引之前自定义用于渲染 Markdown 内容的函数：

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
			options: {
				/**
				 * @param {string} src
				 * @param {import('vitepress').MarkdownEnv} env
				 * @param {import('markdown-it')} md
				 */
				_render(src, env, md) {
					// return html string
				},
			},
		},
	},
})

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
			options: {
				/**
				 * @param {string} src
				 * @param {import('vitepress').MarkdownEnv} env
				 * @param {import('markdown-it')} md
				 */
				_render(src, env, md) {
					// return html string
				},
			},
		},
	},
})

该函数将从客户端站点数据中剥离，因此你可以在其中使用 Node.js API。

示例：从搜索中排除页面

你可以通过将 search: false 添加到页面的 frontmatter 来从搜索中排除页面。或者：

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
			options: {
				_render(src, env, md) {
					const html = md.render(src, env)
					if (env.frontmatter?.search === false) return ''
					if (env.relativePath.startsWith('some/path')) return ''
					return html
				},
			},
		},
	},
})

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
			options: {
				_render(src, env, md) {
					const html = md.render(src, env)
					if (env.frontmatter?.search === false) return ''
					if (env.relativePath.startsWith('some/path')) return ''
					return html
				},
			},
		},
	},
})

注意

如果提供了自定义的 _render 函数，你需要自己处理 search: false 的 frontmatter。此外，在调用 md.render 之前，env 对象不会完全填充，因此对可选 env 属性（如 frontmatter ）的任何检查都应该在此之后完成。

示例：转换内容-添加锚点

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
			options: {
				_render(src, env, md) {
					const html = md.render(src, env)
					if (env.frontmatter?.title) return md.render(`# ${env.frontmatter.title}`) + html
					return html
				},
			},
		},
	},
})

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'local',
			options: {
				_render(src, env, md) {
					const html = md.render(src, env)
					if (env.frontmatter?.title) return md.render(`# ${env.frontmatter.title}`) + html
					return html
				},
			},
		},
	},
})

Algolia Search

VitePress 支持使用 Algolia DocSearch 搜索你的文档站点。请参阅他们的入门指南。在你的 .vitepress/config.ts 中，你至少需要提供以下内容才能使其正常工作：

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'algolia',
			options: {
				appId: '...',
				apiKey: '...',
				indexName: '...',
			},
		},
	},
})

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'algolia',
			options: {
				appId: '...',
				apiKey: '...',
				indexName: '...',
			},
		},
	},
})

i18n

你可以使用这样的配置来使用多语言搜索：

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'algolia',
			options: {
				appId: '...',
				apiKey: '...',
				indexName: '...',
				locales: {
					zh: {
						placeholder: '搜索文档',
						translations: {
							button: {
								buttonText: '搜索文档',
								buttonAriaLabel: '搜索文档',
							},
							modal: {
								searchBox: {
									resetButtonTitle: '清除查询条件',
									resetButtonAriaLabel: '清除查询条件',
									cancelButtonText: '取消',
									cancelButtonAriaLabel: '取消',
								},
								startScreen: {
									recentSearchesTitle: '搜索历史',
									noRecentSearchesText: '没有搜索历史',
									saveRecentSearchButtonTitle: '保存至搜索历史',
									removeRecentSearchButtonTitle: '从搜索历史中移除',
									favoriteSearchesTitle: '收藏',
									removeFavoriteSearchButtonTitle: '从收藏中移除',
								},
								errorScreen: {
									titleText: '无法获取结果',
									helpText: '你可能需要检查你的网络连接',
								},
								footer: {
									selectText: '选择',
									navigateText: '切换',
									closeText: '关闭',
									searchByText: '搜索提供者',
								},
								noResultsScreen: {
									noResultsText: '无法找到相关结果',
									suggestedQueryText: '你可以尝试查询',
									reportMissingResultsText: '你认为该查询应该有结果？',
									reportMissingResultsLinkText: '点击反馈',
								},
							},
						},
					},
				},
			},
		},
	},
})

import { defineConfig } from 'vitepress'

export default defineConfig({
	themeConfig: {
		search: {
			provider: 'algolia',
			options: {
				appId: '...',
				apiKey: '...',
				indexName: '...',
				locales: {
					zh: {
						placeholder: '搜索文档',
						translations: {
							button: {
								buttonText: '搜索文档',
								buttonAriaLabel: '搜索文档',
							},
							modal: {
								searchBox: {
									resetButtonTitle: '清除查询条件',
									resetButtonAriaLabel: '清除查询条件',
									cancelButtonText: '取消',
									cancelButtonAriaLabel: '取消',
								},
								startScreen: {
									recentSearchesTitle: '搜索历史',
									noRecentSearchesText: '没有搜索历史',
									saveRecentSearchButtonTitle: '保存至搜索历史',
									removeRecentSearchButtonTitle: '从搜索历史中移除',
									favoriteSearchesTitle: '收藏',
									removeFavoriteSearchButtonTitle: '从收藏中移除',
								},
								errorScreen: {
									titleText: '无法获取结果',
									helpText: '你可能需要检查你的网络连接',
								},
								footer: {
									selectText: '选择',
									navigateText: '切换',
									closeText: '关闭',
									searchByText: '搜索提供者',
								},
								noResultsScreen: {
									noResultsText: '无法找到相关结果',
									suggestedQueryText: '你可以尝试查询',
									reportMissingResultsText: '你认为该查询应该有结果？',
									reportMissingResultsLinkText: '点击反馈',
								},
							},
						},
					},
				},
			},
		},
	},
})

这些选项可以被覆盖。请参阅官方 Algolia 文档以了解更多信息。

爬虫配置

以下是基于此站点使用的示例配置：

new Crawler({
	appId: '...',
	apiKey: '...',
	rateLimit: 8,
	startUrls: ['https://vitepress.dev/'],
	renderJavaScript: false,
	sitemaps: [],
	exclusionPatterns: [],
	ignoreCanonicalTo: false,
	discoveryPatterns: ['https://vitepress.dev/**'],
	schedule: 'at 05:10 on Saturday',
	actions: [
		{
			indexName: 'vitepress',
			pathsToMatch: ['https://vitepress.dev/**'],
			recordExtractor: ({ $, helpers }) => {
				return helpers.docsearch({
					recordProps: {
						lvl1: '.content h1',
						content: '.content p, .content li',
						lvl0: {
							selectors: '',
							defaultValue: 'Documentation',
						},
						lvl2: '.content h2',
						lvl3: '.content h3',
						lvl4: '.content h4',
						lvl5: '.content h5',
					},
					indexHeadings: true,
				})
			},
		},
	],
	initialIndexSettings: {
		vitepress: {
			attributesForFaceting: ['type', 'lang'],
			attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
			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',
		},
	},
})

new Crawler({
	appId: '...',
	apiKey: '...',
	rateLimit: 8,
	startUrls: ['https://vitepress.dev/'],
	renderJavaScript: false,
	sitemaps: [],
	exclusionPatterns: [],
	ignoreCanonicalTo: false,
	discoveryPatterns: ['https://vitepress.dev/**'],
	schedule: 'at 05:10 on Saturday',
	actions: [
		{
			indexName: 'vitepress',
			pathsToMatch: ['https://vitepress.dev/**'],
			recordExtractor: ({ $, helpers }) => {
				return helpers.docsearch({
					recordProps: {
						lvl1: '.content h1',
						content: '.content p, .content li',
						lvl0: {
							selectors: '',
							defaultValue: 'Documentation',
						},
						lvl2: '.content h2',
						lvl3: '.content h3',
						lvl4: '.content h4',
						lvl5: '.content h5',
					},
					indexHeadings: true,
				})
			},
		},
	],
	initialIndexSettings: {
		vitepress: {
			attributesForFaceting: ['type', 'lang'],
			attributesToRetrieve: ['hierarchy', 'content', 'anchor', 'url'],
			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',
		},
	},
})

搜索 ​

本地搜索 ​

i18n ​

MiniSearch 配置项 ​

自定义渲染内容 ​

示例：从搜索中排除页面 ​

示例：转换内容-添加锚点 ​

Algolia Search ​

i18n ​

爬虫配置 ​

搜索

本地搜索

i18n

MiniSearch 配置项

自定义渲染内容

示例：从搜索中排除页面

示例：转换内容-添加锚点

Algolia Search

i18n

爬虫配置