配置字典:搜索与内容发现
搜索入口、文章收录、语言索引与其他内容入口。
文章目录
先写文章可读写第一篇文章,本地预览和部署见发布教程。配置位置与安装见第一篇教程,其他模块从配置字典总入口进入。
本篇区分两件事:搜索框从构建生成的索引检索文章;首页最新文章、标签、文章底部推荐和 RSS 等是其他内容入口,不由搜索开关统一控制。默认值来自主题包,不是 demo 的覆盖值。
theme.search.enabled:全站搜索开关
- 类型 / 默认值: boolean / true。
- 状态与作用: 生效。公共页头显示搜索入口,参与搜索的文章输出索引标记,构建完成后生成静态 Pagefind 资源。
- 限制: false 同时关闭标准页头入口和本次构建的索引生成;单篇 search: true 不能越过全局关闭状态。关闭不等于删除文章、禁用搜索引擎收录或清除托管平台以前部署的索引文件。
- 示例: theme: { search: { enabled: false } }。
这是唯一的 theme.search 公开叶子字段。没有公开的搜索服务地址、API key、索引目录、结果排序、关键词权重或跨语言检索开关。主题当前使用构建期 Pagefind,部署后不需要单独运行搜索后端。
单篇 search:不是 site.config 字段
| 位置 | 类型 / 默认值 | 状态、作用与限制 | 示例 |
|---|---|---|---|
src/content/blog/<语言>/某篇文章.md 的 frontmatter.search |
boolean,可省略 / schema 未设置,文章布局默认 true | 条件生效:全局搜索开启时决定是否输出该篇索引根标记;false 不影响列表、相关文章、RSS、机器阅读出口或公开文章地址 | search: false |
只排除这篇文章的站内搜索收录,可以在已有 frontmatter 中添加:
search: false
不要把它写成 theme.search: false,或在 site.config 顶层新增 search: false。也不要把 frontmatter.search 当作私密文章开关。当前没有 draft 或未来发布日期过滤;未公开内容应放在内容集合之外。完整文章字段见文章字典。
哪些内容进入索引?
标准文章布局在全局与单篇开关同时允许时输出 data-anglefeint-search 根标记。当前明确标记的正文区域包含文章标题、可见副标题和正文;与副标题相同的 context 只按副标题位置处理一次,不是单独给所有 context 建字段索引。
导航、播放器、页脚、评论和相关文章不作为文章正文一起收录。frontmatter.description 不是此搜索 UI 直接使用的结果摘要,标签也不是可配置的搜索过滤器;搜索结果使用 Pagefind 返回的标题元数据与正文摘要。只出现在图片像素、视频或音频中的文字不会被主题做 OCR 或转写。
默认 About、Fragments、Decoder、首页和列表没有文章索引根标记,不因搜索开关开启而自动成为搜索结果。自定义页面需要自己遵守索引标记约定;这不是添加一个不存在的 site.config 字段就能启用的功能。
messages.search:十一项搜索文案
完整前缀是 i18n.locales.<语言>.messages.search.。以下均为可省略的 string,默认取内置当前语言文案与语言回退链。表中只列中文 / 英文默认值;每行示例是字段值。所有字段条件生效:搜索入口存在且对应界面或状态出现时使用。
| 字段 | 中文 / 英文默认值 | 作用、限制与占位符 | 示例值 |
|---|---|---|---|
label |
搜索 / Search | 搜索入口按钮的无障碍名称、提示及弹窗标题;不是要搜索的关键字 | "搜索文章" |
close |
关闭搜索 / Close search | 关闭按钮的无障碍名称和提示;可见 esc 提示及图标由实现固定 | "关闭搜索" |
placeholder |
搜索文章… / Search articles… | 搜索框占位文字及其无障碍标签;不预填关键字 | "输入文章关键词" |
hint |
搜索当前语言的文章。 / Search articles in the current language. | 生产环境中没有输入关键字时的提示 | "搜索当前语言的文章。" |
loading |
正在搜索… / Searching… | 正在检索或准备检索的提示,不改变延迟与资源加载策略 | "正在查找…" |
empty |
没有找到匹配的文章。 / No matching articles. | 没有结果的提示;当前语言没有索引时也可能显示它 | "没有找到相关文章。" |
error |
搜索加载失败,请重试。 / Search could not load. Please try again. | 索引清单、搜索模块或结果详情加载失败的提示;不用于生成构建错误 | "搜索暂时不可用,请重试。" |
retry |
重试 / Retry | 失败状态的重试按钮文字;点击会重试加载搜索引擎,不会在浏览器重建索引 | "重新加载" |
more |
加载更多 / Load more | 还有未显示结果时的继续加载按钮;不改变每批数量 | "更多结果" |
results |
找到 {count} 篇文章 / {count} articles found | 有结果时的数量提示;保留字面占位符 {count},脚本替换第一个该占位符,不是已展示卡片数 | "共找到 {count} 篇文章" |
dev |
本地完整搜索请先运行 npm run build,再运行 npm run preview。 / To test full search locally, run npm run build, then npm run preview. | dev 模式提示,开发时不执行真实检索;不能靠改文字生成索引 | "请构建后在 preview 中测试搜索。" |
文案按文本输出,不执行配置里的 HTML。空字符串会覆盖文字,不会隐藏相应按钮;错误使用空字符串还可能让控件失去清楚的无障碍名称。results 的 {count} 不会自动附加到你自定义的句子中,想显示数字就保留一次占位符。
可合并的配置示例
合并到 src/site.config.ts 现有 defineThemeConfig({…}),保留 import、export 与其他个人配置,不重复创建 theme 或 i18n:
theme: { search: { enabled: true } },
i18n: {
locales: {
zh: {
messages: {
search: {
label: '搜索文章',
placeholder: '输入文章关键词',
results: '共找到 {count} 篇文章',
empty: '没有找到相关文章。',
},
},
},
},
},
语言、资源加载与结果展示
- 构建输出 pagefind/,包含语言清单 anglefeint.json 和 Pagefind 模块。浏览器打开搜索时才加载清单及搜索引擎;搜索 UI 脚本本身会随含入口的页面加载,不是整套搜索代码都等点击才下载。
- 资源路径自动包含 Astro 的 BASE_URL。只部署 HTML、漏传 pagefind/,或把路径错误重写成 HTML,可能导致加载失败;没有单独的 site.config 索引路径配置。
- 客户端先用文档 html lang 对照索引语言清单,比较时不区分大小写;当前语言没有索引则返回空结果,不切换到英文搜索。这里使用页面有效语言值,不是根据文案的回退语言查询文章。
- 输入约 200 毫秒后检索;中文输入法组合输入结束后再安排检索,提交表单可立即触发。空关键字不执行全文搜索。延迟不是配置字段,也不是请求远端 AI。
- 每批取最多 8 条结果详情,再由“更多”继续加载;没有 pageSize 配置。数量提示使用找到的结果总数,不是当前批次条数。结果只保留同源链接,摘要只保留文本和关键词 mark 高亮,不渲染文章里的任意 HTML。
- 结果顺序由 Pagefind 返回;没有主题级排序或推荐算法参数。普通翻译回退不会把另一语言的文章补入结果。
语言元数据、启停和回退见语言字典。search 文案只改变界面,不会生成对应语言文章或改变索引语言。
为什么 dev 中没有真实搜索?
索引在 Astro 构建结束后生成,npm run dev 不执行这一步。开发环境会显示 messages.search.dev 提示;即使输入关键词也不会真正检索。这是当前行为,不是搜索失效或少填配置。
准备好内容后,在本地运行:
npm run build
npm run preview
preview 使用构建产物;编辑文章、语言元数据、单篇收录开关或站点路径后,想检验新索引需要重新构建。正式站点要一起部署网页与 pagefind 资源。开着 dev 修改文案不等于线上索引已经更新。
没有可索引文章时仍会生成可识别的空语言清单,UI 可以显示空结果。构建期索引失败会报错,不会默默发布一个伪造的成功索引。重试按钮只重试读取已有资源,不能在访客浏览器中修复构建或生成缺失文章。
其他内容发现入口使用哪些配置?
下面沿用各模块已有字段与默认值;主说明仍在原字典,不新增另一套搜索配置。
| 配置路径或位置 | 类型 / 默认值 | 实际作用与限制、示例 | 详细说明 |
|---|---|---|---|
| theme.homeLatestCount | number / 3 | 首页最新文章数量;如 theme: { homeLatestCount: 5 }。不改变搜索结果批次或文章底部相关文章数量 | 首页数量 |
| theme.blogPageSize | number / 10 | Blog List 与标签文章列表每页数量;如 theme: { blogPageSize: 8 }。不是搜索结果数量 | 列表分页 |
| theme.tags.enabled | boolean / true | 标签入口与标准标签页;如 theme: { tags: { enabled: false } }。关闭不删除文章 tags,也不关闭站内全文搜索 | 标签开关 |
| 文章 frontmatter.tags | string[],可省略 / 未设置 | 用于标签归档与页面标签显示;例值 [‘Astro’, ‘随笔’]。不参与当前“相关文章”的相关度计算,也不是搜索白名单 | 文章字段 |
i18n.locales.<语言>.messages.blog.related |
string / 内置当前语言,中文与英文见下表 | 文章底部相关文章标题,只改文案;例值 ‘继续阅读’ | 文章文案 |
i18n.locales.<语言>.messages.blog.relatedAria |
string / 内置当前语言,中文与英文见下表 | 相关文章区域无障碍名称;例值 ‘其他文章’ | 文章文案 |
相关文章实际选取当前语言中排除自身后的最新三篇,不依据共同标签、canonicalTopic 或内容相似度。没有独立 relatedCount、相关文章开关或手动推荐名单的 site.config 字段;没有其他文章时不显示该区域。search: false 的文章仍可能被推荐。
| 文案 | 中文 / 英文默认值 |
|---|---|
| messages.blog.related | 相关文章 / Related |
| messages.blog.relatedAria | 相关文章 / Related posts |
RSS、SEO 和机器阅读出口不是站内搜索
| 入口 | 当前行为及配置关系 |
|---|---|
/<语言>/rss.xml |
每个启用语言的文章摘要订阅;标题使用全站名称,描述使用该语言 messages.blog.archiveDescription。条目来自该语言文章的 title、description、pubDate 与公开路径;不因单篇 search: false 排除,也不是全文 RSS。没有 theme.search 内的 RSS 开关 |
| 页面元信息与搜索引擎 | 与站内搜索索引是不同输出;search: false 不自动添加 noindex 或关闭 sitemap,不能用它控制互联网搜索引擎抓取 |
| 公开机器阅读文本 | 文章、About、Fragments 等有自己的导出管线,不依赖 Pagefind 收录;语言级公开补充见语言字典。search: false 不作为这些产物的私密过滤器 |
站点名称、域名和订阅描述应填写真实值;部署与公开地址见发布教程,RSS 使用的 archiveDescription 见列表文案。不要把“站内没有结果”理解成“网站没有公开这个内容”。
当前全局搜索开关、单篇 search 和十一项搜索文案都有消费位置,没有需要填写的旧搜索兼容字段。canonicalTopic 等当前不消费的文章字段,也不会因为放在搜索附近就自动成为索引分类;相关状态见文章字典。没有公开的跨语言合并搜索、图片 OCR、搜索词分析、搜索结果权重或新增索引类型设置。
返回配置字典总入口查其他模块。