搜索插件设计
@cogita/plugin-search 提供可复用的本地内容搜索索引和 /search 页面。它建立在共享 ContentIndex 之上,不替换 Rspress 默认的文档搜索。
目标与边界
- 构建期生成标准化搜索文档,浏览器运行时执行查询;
- 默认索引标题、摘要、标签和分类,正文需显式开启;
- 主题负责输入框、结果卡片和交互样式;
- 保留 Rspress 搜索弹窗,不覆盖其内部虚拟模块;
- 分析事件默认关闭,不主动向第三方服务发送数据。
一期不实现服务端搜索、外部搜索服务、结果分页和复杂布尔查询。
配置
export default defineConfig({
search: {
enabled: true,
routePrefix: 'search',
includeContent: true,
maxContentLength: 12_000,
maxResults: 20,
fields: {
title: true,
description: true,
tags: true,
categories: true,
content: true,
},
},
});
analytics.enabled 默认关闭;若显式开启,查询词和筛选条件仍需分别授权,默认不进入事件。
数据契约
interface SearchDocument {
id: string;
title: string;
route: string;
url: string;
description?: string;
excerpt?: string;
tags?: string[];
categories?: string[];
content?: string;
createDate: string;
updateDate: string;
image?: string;
imageAlt?: string;
}
virtual-search-data 暴露 searchConfig、searchDocuments 和 searchIndexHash。id 使用文章 route,保证文章列表、分类和搜索结果可以互相关联。
页面与主题
插件新增 /search 页面和 pageLayouts.search 布局。Lucid 主题支持关键词高亮、标签和分类筛选、q/tag/category URL 参数、空查询提示和 site.base 子路径部署。
正文索引会先移除 frontmatter、代码围栏和 HTML 标签,再按 maxContentLength 截断并生成上下文摘要。高亮文本必须以安全的 React 节点渲染。
架构关系
Search、blog-list、tags、categories 和 sitemap 应共享同一内容索引和路由规则。搜索只提供索引和页面,不负责主题布局或独立内容扫描。
验收
- 未配置搜索时现有站点输出不改变;
- 配置后生成
/search,中文标题、标签和分类可检索;
- 正文长度受配置限制,摘要不包含 frontmatter 和代码块;
/cogita/search.html 及结果链接可访问;
- SEO 收录搜索入口,sitemap 不收录动态查询 URL;
- 搜索分析无网络副作用,且
site.base 下链接正确。
详见内容索引设计和插件 API 规范。