SiteSearchPlugin 插件说明文档

一、插件概述

SiteSearchPlugin 是为 Grav CMS 开发的站内搜索插件，支持全文搜索文章标题和内容，按照关键词匹配筛选结果，并提供分页和高亮显示功能。插件通过特定路由触发搜索，适合在站点内快速实现文章查找。

二、核心功能

• 页面内容搜索：遍历所有页面，匹配关键词（支持多词），筛选相关文章。
• 排除目录：支持配置正则表达式，排除特定目录或文件。
• 关键词高亮：搜索关键词可在摘要和标题中高亮显示（可配置关闭）。
• 分页支持：返回分页结果，支持自定义每页数量。
• 结果统计：返回总结果数，便于前端分页显示。
• 支持多标签和分类：通过页面的 taxonomy 获取标签和分类信息。

三、代码结构分析

1. 事件注册

• getSubscribedEvents()：注册事件：
  • onPagesInitialized：初始化页面后执行搜索逻辑。
  • onTwigTemplatePaths：添加模板路径（可自定义模板）。
  • autoload()：引入 Composer 自动加载。

2. 路由监听

• 路径匹配：在 onPagesInitialized() 方法中，判断当前 URI 是否与配置的路由（默认为 /search）匹配，匹配则调用 handleRequest()。

3. 核心搜索逻辑

• sitesearch() 方法：
  • 获取配置参数（排除规则、每页条数、摘要长度、高亮开启等）。
  • 获取关键词参数（支持多词，用空白或“+”拆分）。
  • 遍历所有页面：
  • 排除符合正则的目录或文件。
  • 提取页面标题、分类、标签、内容。
  • 关键词匹配（支持模糊匹配或正则）。
  • 满足条件的页面加入结果数组。
  • 计算分页偏移，返回对应页数据。
  • 输出 JSON 格式的搜索结果。

4. 辅助方法

• isExcluded()：判断页面路径是否匹配排除规则。
• getPageContent()：提取页面的标题、分类、标签和内容，用于搜索匹配。
• matchKeywords()：判断关键词是否出现在页面内容中（支持包含和正则）。
• getSummary()：生成内容摘要，包含关键词附近的内容，支持高亮。
• highlight()：关键词高亮显示（用 <mark> 标签），可关闭。

四、配置参数说明（blueprints.yaml）

五、使用方法

1. 配置插件参数（在 blueprints.yaml 中修改，或在后台配置）。
2. 在站点页面中访问 yourdomain/search（或你自定义的路由路径）。
3. 在搜索框输入关键词，提交后会返回 JSON 格式的搜索结果。
4. 前端可以根据返回的分页信息展示内容，关键词会高亮。

六、示例请求

• 搜索关键词：grav plugin
• 请求URL：/search?keywords=grav+plugin&page=1&per_page=10

返回示例（简化版）：

{
  "results": [
    {
      "title": "Grav CMS插件开发指南",
      "link": "/blog/grav-plugins",
      "content": "本文介绍了如何开发Grav插件...",
      "category": ["开发", "教程"]
    }
  ],
  "total": 3,
  "per_page": 10,
  "page": 1
}

![sitesearch](sitesearch.png "sitesearch")

七、插件下载

sitesearch_plugins.zip