搜索功能

ShokaX 主题集成了 Pagefind 搜索引擎，提供快速、离线的全文搜索体验。

功能特点

快速响应：客户端搜索，无需服务器
离线可用：构建时生成索引，无需外部服务
轻量级：按需加载，首屏不影响性能
自动索引：构建时自动提取文章内容
明暗模式：自动适配主题样式

使用搜索

打开搜索面板

点击导航栏右上角的 🔍 搜索图标 即可打开搜索面板。

快捷键（规划中）：

Ctrl + K 或 Cmd + K（macOS）

搜索文章

在搜索框中输入关键词
实时显示匹配结果
点击任意结果跳转到对应文章
点击右下角 ✕ 关闭搜索面板

工作原理

索引生成

在每次生产构建时，Pagefind 会自动：

扫描 dist/ 目录下的所有 HTML 文件
提取标记为 data-pagefind-body 的内容
生成搜索索引文件（pagefind/ 目录）
构建分词数据库

构建命令：

bun run build

这个命令执行两步：

bun run build:site - 构建 Astro 站点
bun run build:index - 生成 Pagefind 索引

标记可搜索内容

主题已自动为文章内容添加 data-pagefind-body 属性：

<div class="body md" itemprop="articleBody" data-pagefind-body>
  <slot />
</div>

这意味着：

✅ 文章正文内容会被索引
❌ 导航栏、侧边栏、页脚等不会被索引

搜索 UI

搜索面板使用 @pagefind/default-ui 组件，在 SearchPage.svelte 中初始化：

new PagefindUI({
  element: "#pagefind",
  showSubResults: true  // 显示子结果（标题层级）
});

自定义配置

修改可搜索范围

如果你想让其他内容也可被搜索，添加 data-pagefind-body 属性：

<div data-pagefind-body>
  <!-- 这里的内容会被 Pagefind 索引 -->
  <p>你的内容...</p>
</div>

排除特定内容：

<div data-pagefind-body>
  <p>这段会被索引</p>
  <div data-pagefind-ignore>
    这段不会被索引（例如代码、引用来源等）
  </div>
</div>

自定义元数据

为搜索结果添加更多信息（如标签、分类）：

<article
  data-pagefind-body
  data-pagefind-meta="category:Frontend, tags:Astro,Svelte"
>
  <!-- 文章内容 -->
</article>

配置 Pagefind 选项

编辑 package.json 修改索引生成选项：

{
  "scripts": {
    "build:index": "bunx --bun pagefind --site ./dist --glob \"**/*.html\""
  }
}

常用选项：

选项	说明	示例
`--site`	指定网站目录	`--site ./dist`
`--glob`	过滤 HTML 文件	`--glob "posts/*/.html"`
`--exclude-selectors`	排除 CSS 选择器	`--exclude-selectors ".no-index"`
`--force-language`	指定语言	`--force-language zh`

更多选项见 Pagefind CLI 文档。

自定义搜索 UI 样式

编辑 src/components/search/SearchPage.svelte 的样式：

<style>
  :global(.pagefind-ui__results-area),
  :global(.pagefind-ui__result-link),
  :global(.pagefind-ui__result-excerpt),
  :global(.pagefind-ui__message) {
    color: var(--grey-9) !important;
  }

  .pagefind {
    /* 自定义搜索面板样式 */
    background: var(--your-color);
    border-radius: 1rem;
    /* ... */
  }
</style>

开发环境

本地开发时搜索不可用？

原因：开发模式（bun run dev）不会生成 Pagefind 索引。

解决方案：

方案 1：构建后预览
Terminal window
```
bun run build
bun run preview
```
方案 2：仅生成索引（需先构建一次）
Terminal window
```
bun run build:site
bun run build:index
bun run preview
```

常见问题

Q: 搜索结果不准确？

重新生成索引：

bun run build

确保文章内容包含在 data-pagefind-body 标记的元素内。

Q: 某些文章搜不到？

检查：

文章是否被正确构建（查看 dist/ 目录）
文章内容是否在 data-pagefind-body 范围内
是否有 data-pagefind-ignore 意外排除了内容

Q: 如何搜索草稿文章？

默认情况下，未发布的文章不会被构建，因此不会被索引。如需搜索草稿，需要先将文章设置为已发布状态。

Q: 支持中文分词吗？

支持。Pagefind 自动检测语言并使用对应的分词策略。中文、日文等 CJK 语言会使用 n-gram 分词。

Q: 搜索能识别拼音吗？

不支持。Pagefind 基于精确匹配和模糊匹配，不支持拼音转汉字。

Q: 如何实现搜索统计？

Pagefind 本身不提供统计功能。如需实现，可以：

在搜索组件中监听搜索事件
发送统计数据到第三方分析服务（如 Google Analytics）

示例（需修改 SearchPage.svelte）：

new PagefindUI({
  element: "#pagefind",
  onSearch: (query) => {
    // 统计搜索关键词
    gtag('event', 'search', { search_term: query });
  }
});

Q: 能否集成其他搜索服务？

可以。如果你想使用 Algolia、Meilisearch 等服务：

删除或注释 SearchPage.svelte 组件
集成对应搜索服务的 SDK
修改导航栏搜索按钮的触发逻辑

但这会失去 Pagefind 的离线和轻量级优势。