hexo-semantic-search-ai 1.0.0

package/README.md

@@ -0,0 +1,201 @@
+# hexo-semantic-search-ai [中文](README.zh-CN.md)
+
+A Hexo plugin that integrates [SemanticSearch](https://github.com/SemanticSearch-ai/semanticsearch) for AI-powered semantic search and related posts.
+
+## Features
+
+- **Automatic Indexing**: Syncs posts to SemanticSearch after `hexo generate`
+- **Incremental Sync**: Only syncs changed posts (tracks content hash)
+- **Related Posts**: Generates related posts at build time using semantic similarity
+- **Search Component**: Provides helpers for frontend search UI
+- **Customizable**: Full control over styling and rendering
+
+## Installation
+
+```bash
+npm install hexo-semantic-search-ai --save
+```
+
+## Prerequisites
+
+You need a SemanticSearch instance. Deploy one for free on Cloudflare Workers:
+
+1. Go to [SemanticSearch](https://github.com/SemanticSearch-ai/semanticsearch)
+2. Click "Deploy to Cloudflare"
+3. Get your API endpoint and keys
+
+## Configuration
+
+Add to your Hexo `_config.yml`:
+
+```yaml
+semantic_search:
+  enable: true
+  endpoint: https://your-search.your-subdomain.workers.dev
+  writer_key: ${SEMANTIC_SEARCH_WRITER_KEY}  # Use env var for security
+  reader_key: your-reader-key                 # Public, safe to expose
+
+  # Sync settings
+  sync:
+    auto: true                    # Auto-sync after hexo generate
+    fields:                       # Fields to index
+      - title
+      - content
+      - excerpt
+      - tags
+      - categories
+
+  # Related posts settings
+  related_posts:
+    enable: true
+    limit: 5                      # Max related posts per article
+    min_score: 0.3                # Minimum similarity score (0-1)
+    query_fields:                 # Fields used to find related posts
+      - title
+      - excerpt
+
+  # Search UI settings
+  search:
+    placeholder: "Search..."
+```
+
+### Environment Variables
+
+For security, use environment variables for your writer key:
+
+```bash
+export SEMANTIC_SEARCH_WRITER_KEY=your-writer-key
+```
+
+## Usage
+
+### Search Box
+
+Add a search box to your theme:
+
+```ejs
+<%- semantic_search_box() %>
+```
+
+With options:
+
+```ejs
+<%- semantic_search_box({
+  placeholder: 'Search articles...',
+  class: 'my-search-box',
+  id: 'custom-search'
+}) %>
+```
+
+Don't forget to include the JS file:
+
+```ejs
+<script src="<%- url_for('/js/semantic-search.js') %>"></script>
+```
+
+### Related Posts
+
+Display related posts in your post template:
+
+```ejs
+<%- semantic_related_posts() %>
+```
+
+With options:
+
+```ejs
+<%- semantic_related_posts({
+  limit: 3,
+  title: 'You might also like',
+  class: 'related-articles',
+  excerpt: false
+}) %>
+```
+
+### Custom Rendering
+
+For full control, access the raw data:
+
+```ejs
+<% if (has_semantic_related()) { %>
+  <div class="my-related-posts">
+    <h3>Related</h3>
+    <% get_semantic_related().forEach(function(post) { %>
+      <article>
+        <a href="<%= post.url %>"><%= post.title %></a>
+        <p><%= post.excerpt %></p>
+      </article>
+    <% }); %>
+  </div>
+<% } %>
+```
+
+### Frontend JavaScript API
+
+For advanced use cases, use the JavaScript API directly:
+
+```html
+<script src="/js/semantic-search.js"></script>
+<script>
+  // Configure (if not using helper)
+  SemanticSearch.configure({
+    endpoint: 'https://your-search.workers.dev',
+    readerKey: 'your-reader-key'
+  });
+
+  // Search
+  SemanticSearch.search('how to deploy').then(results => {
+    console.log(results);
+  });
+
+  // Or bind to an input
+  SemanticSearch.bindSearchBox('#search-input', '#search-results', {
+    limit: 10,
+    debounce: 300,
+    minLength: 2
+  });
+</script>
+```
+
+## Commands
+
+### Sync manually
+
+```bash
+# Incremental sync (only changed posts)
+hexo semantic-search sync
+
+# Force full sync
+hexo semantic-search sync --force
+# or
+hexo semantic-search full-sync
+
+# Check sync status
+hexo semantic-search status
+```
+
+## State File
+
+The plugin creates `.semantic-search-state.json` in your Hexo root to track synced posts. Add it to `.gitignore` if you don't want to commit it:
+
+```
+.semantic-search-state.json
+```
+
+## Helpers Reference
+
+| Helper | Description |
+|--------|-------------|
+| `semantic_search_box(options)` | Render search input with results container |
+| `semantic_search_config()` | Output config JSON for custom frontend |
+| `semantic_related_posts(options)` | Render related posts list |
+| `has_semantic_related()` | Check if current post has related posts |
+| `get_semantic_related()` | Get raw related posts array |
+
+## License
+
+MIT
+
+## Friendly Request
+
+Friendly request (not required): If you use this plugin, please consider adding a link to https://semanticsearch.ai/ on your website.

package/README.zh-CN.md

@@ -0,0 +1,201 @@
+# hexo-semantic-search-ai [English](README.md)
+
+一个 Hexo 插件，集成 [SemanticSearch](https://github.com/SemanticSearch-ai/semanticsearch)，为静态博客提供 AI 语义搜索与相关文章推荐。
+
+## 功能特性
+
+- **自动索引**：在 `hexo generate` 后同步文章到 SemanticSearch
+- **增量同步**：仅同步变更文章（跟踪内容哈希）
+- **相关文章**：构建时基于语义相似度生成相关文章
+- **搜索组件**：提供前端搜索 UI 的 helper
+- **可定制**：完全可控的样式与渲染
+
+## 安装
+
+```bash
+npm install hexo-semantic-search-ai --save
+```
+
+## 前置条件
+
+你需要一个 SemanticSearch 实例。可以在 Cloudflare Workers 上免费部署：
+
+1. 访问 [SemanticSearch](https://github.com/SemanticSearch-ai/semanticsearch)
+2. 点击 “Deploy to Cloudflare”
+3. 获取 API Endpoint 和密钥
+
+## 配置
+
+在 Hexo `_config.yml` 中添加：
+
+```yaml
+semantic_search:
+  enable: true
+  endpoint: https://your-search.your-subdomain.workers.dev
+  writer_key: ${SEMANTIC_SEARCH_WRITER_KEY}  # 为了安全使用环境变量
+  reader_key: your-reader-key                 # 公钥，可公开
+
+  # 同步设置
+  sync:
+    auto: true                    # 在 hexo generate 后自动同步
+    fields:                       # 需要索引的字段
+      - title
+      - content
+      - excerpt
+      - tags
+      - categories
+
+  # 相关文章设置
+  related_posts:
+    enable: true
+    limit: 5                      # 每篇文章最多相关条目
+    min_score: 0.3                # 相似度阈值 (0-1)
+    query_fields:                 # 用于检索相关文章的字段
+      - title
+      - excerpt
+
+  # 搜索 UI 设置
+  search:
+    placeholder: "搜索..."
+```
+
+### 环境变量
+
+为了安全，建议使用环境变量保存 writer key：
+
+```bash
+export SEMANTIC_SEARCH_WRITER_KEY=your-writer-key
+```
+
+## 使用
+
+### 搜索框
+
+在主题中添加搜索框：
+
+```ejs
+<%- semantic_search_box() %>
+```
+
+可选参数：
+
+```ejs
+<%- semantic_search_box({
+  placeholder: '搜索文章...',
+  class: 'my-search-box',
+  id: 'custom-search'
+}) %>
+```
+
+别忘了引入 JS 文件：
+
+```ejs
+<script src="<%- url_for('/js/semantic-search.js') %>"></script>
+```
+
+### 相关文章
+
+在文章模板中显示相关文章：
+
+```ejs
+<%- semantic_related_posts() %>
+```
+
+可选参数：
+
+```ejs
+<%- semantic_related_posts({
+  limit: 3,
+  title: '你可能也喜欢',
+  class: 'related-articles',
+  excerpt: false
+}) %>
+```
+
+### 自定义渲染
+
+如需完全控制，可直接获取原始数据：
+
+```ejs
+<% if (has_semantic_related()) { %>
+  <div class="my-related-posts">
+    <h3>相关内容</h3>
+    <% get_semantic_related().forEach(function(post) { %>
+      <article>
+        <a href="<%= post.url %>"><%= post.title %></a>
+        <p><%= post.excerpt %></p>
+      </article>
+    <% }); %>
+  </div>
+<% } %>
+```
+
+### 前端 JavaScript API
+
+高级用法可直接使用 JavaScript API：
+
+```html
+<script src="/js/semantic-search.js"></script>
+<script>
+  // 配置（如果不使用 helper）
+  SemanticSearch.configure({
+    endpoint: 'https://your-search.workers.dev',
+    readerKey: 'your-reader-key'
+  });
+
+  // 搜索
+  SemanticSearch.search('how to deploy').then(results => {
+    console.log(results);
+  });
+
+  // 或绑定到输入框
+  SemanticSearch.bindSearchBox('#search-input', '#search-results', {
+    limit: 10,
+    debounce: 300,
+    minLength: 2
+  });
+</script>
+```
+
+## 命令
+
+### 手动同步
+
+```bash
+# 增量同步（仅同步变更文章）
+hexo semantic-search sync
+
+# 强制全量同步
+hexo semantic-search sync --force
+# 或
+hexo semantic-search full-sync
+
+# 查看同步状态
+hexo semantic-search status
+```
+
+## 状态文件
+
+插件会在 Hexo 根目录创建 `.semantic-search-state.json` 用于追踪已同步的文章。如果不想提交，请加入 `.gitignore`：
+
+```
+.semantic-search-state.json
+```
+
+## Helper 参考
+
+| Helper | 说明 |
+|--------|------|
+| `semantic_search_box(options)` | 渲染搜索输入框与结果容器 |
+| `semantic_search_config()` | 输出自定义前端所需的配置 JSON |
+| `semantic_related_posts(options)` | 渲染相关文章列表 |
+| `has_semantic_related()` | 判断当前文章是否有相关文章 |
+| `get_semantic_related()` | 获取原始相关文章数组 |
+
+## 许可
+
+MIT
+
+## 友好请求
+
+友好请求（非强制）：如果你在网站中使用了本插件，欢迎在你的网站上添加指向 https://semanticsearch.ai/ 的链接。

package/assets/semantic-search.js

@@ -0,0 +1,175 @@
+/**
+ * SemanticSearch Frontend Client
+ * Lightweight browser-side search client
+ */
+(function(window) {
+  'use strict';
+
+  var config = window.SEMANTIC_SEARCH_CONFIG || {};
+
+  var SemanticSearch = {
+    endpoint: config.endpoint,
+    readerKey: config.readerKey,
+
+    /**
+     * Configure the client
+     */
+    configure: function(options) {
+      this.endpoint = options.endpoint || this.endpoint;
+      this.readerKey = options.readerKey || this.readerKey;
+    },
+
+    /**
+     * Search documents
+     */
+    search: function(query, options) {
+      var self = this;
+      options = options || {};
+
+      return new Promise(function(resolve, reject) {
+        if (!self.endpoint) {
+          reject(new Error('SemanticSearch endpoint not configured'));
+          return;
+        }
+
+        var xhr = new XMLHttpRequest();
+        xhr.open('POST', self.endpoint + '/v1/search', true);
+        xhr.setRequestHeader('Content-Type', 'application/json');
+
+        if (self.readerKey) {
+          xhr.setRequestHeader('Authorization', 'Bearer ' + self.readerKey);
+        }
+
+        xhr.onreadystatechange = function() {
+          if (xhr.readyState === 4) {
+            if (xhr.status >= 200 && xhr.status < 300) {
+              try {
+                var response = JSON.parse(xhr.responseText);
+                resolve(response.results || response || []);
+              } catch (e) {
+                reject(new Error('Failed to parse response'));
+              }
+            } else {
+              reject(new Error('Search failed: ' + xhr.status));
+            }
+          }
+        };
+
+        xhr.onerror = function() {
+          reject(new Error('Network error'));
+        };
+
+        xhr.send(JSON.stringify({
+          query: query,
+          limit: options.limit || 10
+        }));
+      });
+    },
+
+    /**
+     * Bind search box with auto-complete
+     */
+    bindSearchBox: function(inputSelector, resultSelector, options) {
+      var self = this;
+      options = options || {};
+
+      var input = typeof inputSelector === 'string'
+        ? document.querySelector(inputSelector)
+        : inputSelector;
+      var resultContainer = typeof resultSelector === 'string'
+        ? document.querySelector(resultSelector)
+        : resultSelector;
+
+      if (!input || !resultContainer) {
+        console.warn('SemanticSearch: Input or result container not found');
+        return;
+      }
+
+      var debounceTimer;
+      var minLength = options.minLength || 2;
+      var debounceMs = options.debounce || 300;
+
+      input.addEventListener('input', function() {
+        var query = input.value.trim();
+
+        clearTimeout(debounceTimer);
+
+        if (query.length < minLength) {
+          resultContainer.innerHTML = '';
+          resultContainer.style.display = 'none';
+          return;
+        }
+
+        debounceTimer = setTimeout(function() {
+          self.search(query, { limit: options.limit || 10 })
+            .then(function(results) {
+              self._renderResults(resultContainer, results, options);
+            })
+            .catch(function(error) {
+              console.error('SemanticSearch error:', error);
+              resultContainer.innerHTML = '<div class="semantic-search-error">Search failed</div>';
+              resultContainer.style.display = 'block';
+            });
+        }, debounceMs);
+      });
+
+      // Hide results on click outside
+      document.addEventListener('click', function(e) {
+        if (!input.contains(e.target) && !resultContainer.contains(e.target)) {
+          resultContainer.style.display = 'none';
+        }
+      });
+    },
+
+    /**
+     * Render search results
+     */
+    _renderResults: function(container, results, options) {
+      if (!results || results.length === 0) {
+        container.innerHTML = '<div class="semantic-search-no-results">' +
+          (options.noResultsText || 'No results found') + '</div>';
+        container.style.display = 'block';
+        return;
+      }
+
+      var html = '<ul class="semantic-search-result-list">';
+      for (var i = 0; i < results.length; i++) {
+        var item = results[i];
+        // API returns: { document: { id, text, metadata }, score }
+        var meta = (item.document && item.document.metadata) || item.metadata || {};
+        var title = meta.title || (item.document && item.document.id) || item.title || 'Untitled';
+        var url = meta.url || item.url || '#';
+        var excerpt = meta.excerpt || item.excerpt || '';
+
+        html += '<li class="semantic-search-result-item">';
+        html += '<a href="' + url + '" class="semantic-search-result-link">' + title + '</a>';
+        if (excerpt && options.showExcerpt !== false) {
+          var shortExcerpt = excerpt.substring(0, 100) + (excerpt.length > 100 ? '...' : '');
+          html += '<p class="semantic-search-result-excerpt">' + shortExcerpt + '</p>';
+        }
+        html += '</li>';
+      }
+      html += '</ul>';
+
+      container.innerHTML = html;
+      container.style.display = 'block';
+    }
+  };
+
+  // Auto-init if config exists
+  if (config.endpoint) {
+    document.addEventListener('DOMContentLoaded', function() {
+      var searchBox = document.querySelector('.semantic-search-box');
+      if (searchBox) {
+        var input = searchBox.querySelector('.semantic-search-input');
+        var results = searchBox.querySelector('.semantic-search-results');
+        if (input && results) {
+          SemanticSearch.bindSearchBox(input, results);
+        }
+      }
+    });
+  }
+
+  window.SemanticSearch = SemanticSearch;
+
+})(window);