jekyll-client-search 0.3.5 → 0.5.0

data/assets/client-search-dropdown.js

@@ -9,8 +9,8 @@
      * Features:
      *   - Lazy index loading (fetches search-index.json on first keystroke)
      *   - Two-stage search (AND first, fuzzy OR fallback) via engine adapter
-     *   - Compact <li><a> items with optional icon rendering
-     *   - Keyboard navigation (Arrow Up/Down, Enter, Escape)
+     *   - ARIA combobox + listbox with plain-text options and optional icons
+     *   - Active-descendant keyboard navigation (Arrow Up/Down, Enter, Escape)
      *   - Enter with no selection → redirect to redirect_url (?q=...)
      *   - Click outside or Escape → close dropdown
      *   - Multi-instance via [data-client-search-dropdown] attributes
@@ -20,6 +20,8 @@
     var sharedIndex = null;
     var sharedDocuments = null;
     var indexLoadPromise = null;
+    var nextDropdownInstanceId = 0;
+    var initializedRoots = new WeakSet();
 
     function safeUrl(value) {
         if (value === "#") {
@@ -116,25 +118,27 @@
         });
     }
 
-    function createResultItem(match, documents, iconField) {
+    function createResultItem(match, documents, iconField, optionId) {
         var entry = documents.get(match.ref);
         if (!entry) {
             return null;
         }
 
-        var li = document.createElement("li");
-        li.setAttribute("role", "option");
-        li.className = "client-search-dropdown-item";
-        li.dataset.url = safeUrl(entry.url);
+        var option = document.createElement("li");
+        option.id = optionId;
+        option.setAttribute("role", "option");
+        option.setAttribute("aria-selected", "false");
+        option.className = "client-search-dropdown-item";
+        option.dataset.url = safeUrl(entry.url);
 
         if (entry.source) {
-            li.dataset.source = entry.source;
+            option.dataset.source = entry.source;
         }
         if (entry.categories && entry.categories.length) {
-            li.dataset.categories = entry.categories.join(" ");
+            option.dataset.categories = entry.categories.join(" ");
         }
         if (entry.tags && entry.tags.length) {
-            li.dataset.tags = entry.tags.join(" ");
+            option.dataset.tags = entry.tags.join(" ");
         }
         Object.keys(entry).forEach(function (key) {
             var skip = ["id", "title", "url", "excerpt", "content",
@@ -145,7 +149,7 @@
             }
             var value = entry[key];
             if (typeof value === "string" || typeof value === "number") {
-                li.dataset[toCamelCase(key)] = String(value);
+                option.dataset[toCamelCase(key)] = String(value);
             }
         });
 
@@ -153,22 +157,21 @@
             var icon = document.createElement("img");
             icon.className = "client-search-dropdown-icon";
             icon.src = safeUrl(entry[iconField]);
-            icon.alt = entry.file_type || entry.source || "";
+            icon.alt = "";
+            icon.setAttribute("aria-hidden", "true");
             icon.loading = "lazy";
             icon.style.width = "1em";
             icon.style.height = "1em";
             icon.style.verticalAlign = "middle";
-            icon.style.marginRight = "0.3em";
-            li.appendChild(icon);
+            option.appendChild(icon);
         }
 
-        var link = document.createElement("a");
-        link.href = safeUrl(entry.url);
-        link.textContent = entry.title;
-        link.className = "client-search-dropdown-link";
-        li.appendChild(link);
+        var title = document.createElement("span");
+        title.className = "client-search-dropdown-link";
+        title.textContent = entry.title;
+        option.appendChild(title);
 
-        return li;
+        return option;
     }
 
     function DropdownInstance(root, config) {
@@ -176,6 +179,7 @@
         this.form = root.querySelector("[data-cs-dropdown-form]");
         this.input = root.querySelector("[data-cs-dropdown-input]");
         this.results = root.querySelector("[data-cs-dropdown-results]");
+        this.listbox = this.results.closest('[role="listbox"]') || this.results;
         this.config = config;
         this.maxItems = Number.parseInt(this.results.dataset.maxItems, 10) || config.maxItems || 5;
         this.selectedIndex = -1;
@@ -183,6 +187,9 @@
         this.debounceTimer = null;
         this.renderVersion = 0;
         this.adapter = null;
+        this.optionIdPrefix = this.results.id
+            ? this.results.id + "-option"
+            : "cs-dropdown-" + (++nextDropdownInstanceId) + "-option";
     }
 
     DropdownInstance.prototype.init = function () {
@@ -190,6 +197,11 @@
             return;
         }
 
+        this.results.setAttribute("aria-hidden", "true");
+        this.listbox.setAttribute("aria-hidden", "true");
+        this.input.setAttribute("aria-expanded", "false");
+        this.input.removeAttribute("aria-activedescendant");
+
         var self = this;
 
         this.input.addEventListener("input", function () {
@@ -212,9 +224,9 @@
         });
 
         this.results.addEventListener("click", function (event) {
-            var li = event.target.closest("li");
-            if (li && li.dataset.url && li.dataset.url !== "#") {
-                window.location.href = li.dataset.url;
+            var option = event.target.closest('[role="option"]');
+            if (option && option.dataset.url && option.dataset.url !== "#") {
+                window.location.href = option.dataset.url;
             }
         });
     };
@@ -223,10 +235,10 @@
         var self = this;
         this.renderVersion += 1;
         clearTimeout(this.debounceTimer);
+        this.hide();
 
         var query = this.input.value.trim();
         if (!query || query.length < this.config.minChars) {
-            this.hide();
             return;
         }
 
@@ -264,7 +276,6 @@
                 break;
             case "Escape":
                 this.hide();
-                this.input.blur();
                 break;
             case "Tab":
                 this.hide();
@@ -318,6 +329,7 @@
         this.results.replaceChildren();
         this.currentItems = [];
         this.selectedIndex = -1;
+        this.input.removeAttribute("aria-activedescendant");
 
         if (!matches || matches.length === 0) {
             this.hide();
@@ -328,7 +340,12 @@
         var count = Math.min(matches.length, this.maxItems);
 
         for (var i = 0; i < count; i++) {
-            var item = createResultItem(matches[i], documents, iconField);
+            var item = createResultItem(
+                matches[i],
+                documents,
+                iconField,
+                this.optionIdPrefix + "-" + i
+            );
             if (item) {
                 this.results.appendChild(item);
                 this.currentItems.push(item);
@@ -353,18 +370,26 @@
             }
         }
         if (this.currentItems[index]) {
-            this.currentItems[index].scrollIntoView({ block: "nearest" });
+            this.input.setAttribute("aria-activedescendant", this.currentItems[index].id);
+            if (typeof this.currentItems[index].scrollIntoView === "function") {
+                this.currentItems[index].scrollIntoView({ block: "nearest" });
+            }
+        } else {
+            this.input.removeAttribute("aria-activedescendant");
         }
     };
 
     DropdownInstance.prototype.show = function () {
         this.results.setAttribute("aria-hidden", "false");
+        this.listbox.setAttribute("aria-hidden", "false");
         this.input.setAttribute("aria-expanded", "true");
     };
 
     DropdownInstance.prototype.hide = function () {
         this.results.setAttribute("aria-hidden", "true");
+        this.listbox.setAttribute("aria-hidden", "true");
         this.input.setAttribute("aria-expanded", "false");
+        this.input.removeAttribute("aria-activedescendant");
         this.results.replaceChildren();
         this.currentItems = [];
         this.selectedIndex = -1;
@@ -389,6 +414,11 @@
 
         var roots = document.querySelectorAll("[data-client-search-dropdown]");
         roots.forEach(function (root) {
+            if (initializedRoots.has(root)) {
+                return;
+            }
+            initializedRoots.add(root);
+
             var instance = new DropdownInstance(root, mergedConfig);
             instance.init();
         });

data/assets/query-embedders/ollama-api.js

@@ -2,7 +2,7 @@
     "use strict";
 
     var config = window.ClientSearchEmbedderConfig || {};
-    var model = config.model || config.buildModel || "embeddinggemma:300m";
+    var model = config.model || config.buildModel || "embeddinggemma-2:570m";
     var apiUrl = config.apiUrl || "http://localhost:11434/api/embed";
     var activeController = null;
 

data/lib/jekyll/client_search/configuration.rb

@@ -27,7 +27,7 @@ module Jekyll
         "icon_field" => "icon_url",
         "embedding" => {
           "enabled" => false,
-          "model" => "embeddinggemma:300m",
+          "model" => "embeddinggemma-2:570m",
           "base_url" => "http://localhost:11434",
           "connect_timeout" => 5,
           "read_timeout" => 120,
@@ -41,9 +41,7 @@ module Jekyll
       def initialize(site)
         configured = normalize_configured(site.config["client_search"])
         @values = DEFAULTS.merge(configured)
-        @live_search = LiveSearchConfiguration.new(configured["live_search"] || {}, engine: engine)
-        @related = RelatedConfiguration.new(configured["related"] || {})
-        @dropdown = DropdownConfiguration.new(configured["dropdown"] || {})
+        build_sub_configurations(configured)
         merge_embedding_config(configured["embedding"])
         validate_engine!
         return unless embedding_enabled?
@@ -54,6 +52,13 @@ module Jekyll
 
       private
 
+      def build_sub_configurations(configured)
+        @live_search = LiveSearchConfiguration.new(configured["live_search"] || {}, engine: engine)
+        @related = RelatedConfiguration.new(configured["related"] || {})
+        @semantic = SemanticConfiguration.new(configured["semantic"] || {})
+        @dropdown = DropdownConfiguration.new(configured["dropdown"] || {})
+      end
+
       def normalize_configured(value)
         return { "enabled" => false } if value == false
         return value if value.is_a?(Hash)
@@ -70,13 +75,9 @@ module Jekyll
                 "client_search embedding configuration must be a mapping"
         end
         @values["embedding"] = DEFAULTS.fetch("embedding").merge(embedding)
-        merge_query_embedder_config(embedding["query_embedder"])
-      end
-
-      def merge_query_embedder_config(configured_query_embedder)
         @query_embedder = QueryEmbedderConfiguration.new(
-          configured_query_embedder || {},
-          build_model: embedding_model,
+          embedding["query_embedder"] || {},
+          build_model: embedding_index_model,
           build_base_url: embedding_base_url,
           query_prefix: embedding_query_prefix
         )

data/lib/jekyll/client_search/configuration_accessors.rb

@@ -20,6 +20,19 @@ module Jekyll
         @related
       end
 
+      # The Ollama model whose vectors are written into the search index and
+      # must match the browser query embedder's vector space. Defaults to
+      # embedding.model; override with semantic.index_model.
+      def embedding_index_model
+        @semantic.index_model || embedding_model
+      end
+
+      # The Ollama model used for related-article similarity analysis.
+      # Defaults to embedding.model; override with related.index_model.
+      def embedding_related_model
+        @related.index_model || embedding_model
+      end
+
       def query_embedder_type
         @query_embedder.type
       end

data/lib/jekyll/client_search/dropdown_tag.rb

@@ -87,13 +87,17 @@ module Jekyll
           <div class="client-search-dropdown" data-client-search-dropdown>
             <form role="search" autocomplete="off" data-cs-dropdown-form>
               <label class="sr-only" for="#{@input_id}">Search</label>
-              <input id="#{@input_id}" type="search" name="q"
+              <input id="#{@input_id}" type="search" name="q" role="combobox"
+                     aria-autocomplete="list" aria-haspopup="listbox"
                      placeholder="Search…" autocomplete="off"
                      aria-expanded="false" aria-controls="#{@results_id}"
                      data-cs-dropdown-input>
             </form>
-            <ul id="#{@results_id}" role="listbox" aria-hidden="true"
-                data-cs-dropdown-results data-max-items="#{max}"></ul>
+            <div id="#{@results_id}" role="listbox" aria-label="Search suggestions"
+                 aria-hidden="true">
+              <ul role="presentation" aria-hidden="true"
+                  data-cs-dropdown-results data-max-items="#{max}"></ul>
+            </div>
           </div>
         HTML
       end

data/lib/jekyll/client_search/embedding_configuration.rb

@@ -9,9 +9,25 @@ module Jekyll
           "document" => "title: none | text: ",
           "query" => "task: search result | query: "
         },
+        "embeddinggemma-2" => {
+          "document" => "title: none | text: ",
+          "query" => "task: search result | query: "
+        },
         "nomic-embed-text" => {
           "document" => "search_document: ",
           "query" => "search_query: "
+        },
+        "voyage-4-nano" => {
+          "document" => "Represent the document for retrieval: ",
+          "query" => "Represent the query for retrieving supporting documents: "
+        },
+        "qwen3-embedding" => {
+          "document" => "",
+          "query" => "Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery: "
+        },
+        "bge-large" => {
+          "document" => "",
+          "query" => "Represent this sentence for searching relevant passages: "
         }
       }.freeze
 
@@ -44,43 +60,63 @@ module Jekyll
         configured.nil? ? engine == "semantic" : configured == true
       end
 
+      # Document prefix for the index model (semantic.index_model).
       def embedding_document_prefix
-        configured_prefix("document_prefix", "document")
+        configured_prefix("document", model: embedding_index_model, override: @semantic.document_prefix)
       end
 
+      # Query prefix for the index model — must match the browser query
+      # embedder's vector space.
       def embedding_query_prefix
-        configured_prefix("query_prefix", "query")
+        configured_prefix("query", model: embedding_index_model, override: @semantic.query_prefix)
+      end
+
+      # Document prefix for the related-analysis model (related.index_model).
+      def embedding_related_document_prefix
+        configured_prefix("document", model: embedding_related_model)
       end
 
       def embedding_identity
+        embedding_identity_for(model: embedding_index_model,
+                               document_prefix: embedding_document_prefix,
+                               query_prefix: embedding_query_prefix)
+      end
+
+      def embedding_related_identity
+        embedding_identity_for(model: embedding_related_model,
+                               document_prefix: embedding_related_document_prefix,
+                               query_prefix: configured_prefix("query", model: embedding_related_model))
+      end
+
+      private
+
+      def embedding_identity_for(model:, document_prefix:, query_prefix:)
         {
           "provider" => "ollama",
-          "model" => embedding_model,
+          "model" => model,
           "base_url" => embedding_base_url,
-          "document_prefix" => embedding_document_prefix,
-          "query_prefix" => embedding_query_prefix,
+          "document_prefix" => document_prefix,
+          "query_prefix" => query_prefix,
           "schema" => 2
         }
       end
 
-      private
+      def configured_prefix(role, model:, override: nil)
+        return override.to_s if override
 
-      def configured_prefix(config_key, role)
         embedding = @values.fetch("embedding")
-        return embedding.fetch(config_key).to_s if embedding.key?(config_key)
+        config_key = "#{role}_prefix"
+        return embedding[config_key].to_s if model == embedding_model && embedding.key?(config_key)
 
-        model_name = embedding_model.split(":").first
-        PREFIXES.fetch(model_name, {}).fetch(role, "")
+        PREFIXES.fetch(model.split(":").first, {}).fetch(role, "")
       end
 
       def positive_timeout(key)
         value = @values.fetch("embedding").fetch(key).to_f
-        unless value.positive? && value.finite?
-          raise Jekyll::Errors::FatalException,
-                "embedding #{key} must be a finite value greater than zero"
-        end
+        return value if value.positive? && value.finite?
 
-        value
+        raise Jekyll::Errors::FatalException,
+              "embedding #{key} must be a finite value greater than zero"
       end
 
       def validate_embedding!

data/lib/jekyll/client_search/generator.rb

@@ -25,6 +25,7 @@ module Jekyll
 
       def add_generated_pages(site, documents, configuration)
         add_related_page(site, documents, configuration) if configuration.related_enabled?
+        documents.each { |document| document.delete("related_embedding") }
         remove_embeddings(documents) unless configuration.embedding_include_in_index?
         site.pages << SearchIndexPage.new(site, configuration.output, documents)
         site.pages << RuntimeConfigPage.new(site, configuration) if configuration.copy_runtime?
@@ -39,18 +40,60 @@ module Jekyll
       end
 
       def enhance_with_embeddings(site, documents, configuration)
-        cache = IndexCache.new(site.source, embedding_identity: configuration.embedding_identity)
-        adapter = build_embedding_adapter(configuration)
-
-        documents.each { |entry| embed_document(entry, cache, adapter, configuration) }
-        cache.prune(documents.map { |doc| doc["id"] })
-        cache.save
+        embedding_jobs(configuration).each do |job|
+          cache = IndexCache.new(site.source, embedding_identity: job[:identity],
+                                              file_name: job[:cache_file])
+          adapter = build_embedding_adapter(configuration, model: job[:model])
+
+          documents.each { |entry| embed_document(entry, cache, adapter, configuration, job) }
+          cache.prune(documents.map { |doc| doc["id"] })
+          cache.save
+        end
         documents
       end
 
-      def build_embedding_adapter(configuration)
+      # Each job embeds every document once per model into a target field.
+      # The index model writes "embedding" (kept when include_in_index); a
+      # divergent related model writes "related_embedding" (stripped before
+      # the index is emitted). Identical models share a single pass.
+      def embedding_jobs(configuration)
+        jobs = []
+        jobs << index_embedding_job(configuration) if configuration.embedding_include_in_index?
+        jobs.concat(related_embedding_jobs(configuration)) if configuration.related_enabled?
+        jobs
+      end
+
+      def index_embedding_job(configuration)
+        {
+          model: configuration.embedding_index_model,
+          field: "embedding",
+          document_prefix: configuration.embedding_document_prefix,
+          identity: configuration.embedding_identity,
+          cache_file: IndexCache::CACHE_FILE
+        }
+      end
+
+      def related_embedding_jobs(configuration)
+        return [related_embedding_job("embedding", IndexCache::CACHE_FILE, configuration)] unless
+          configuration.embedding_include_in_index?
+        return [] if configuration.embedding_related_model == configuration.embedding_index_model
+
+        [related_embedding_job("related_embedding", IndexCache::RELATED_CACHE_FILE, configuration)]
+      end
+
+      def related_embedding_job(field, cache_file, configuration)
+        {
+          model: configuration.embedding_related_model,
+          field: field,
+          document_prefix: configuration.embedding_related_document_prefix,
+          identity: configuration.embedding_related_identity,
+          cache_file: cache_file
+        }
+      end
+
+      def build_embedding_adapter(configuration, model: configuration.embedding_model)
         OllamaEmbeddingAdapter.new(
-          model: configuration.embedding_model,
+          model: model,
           base_url: configuration.embedding_base_url,
           connect_timeout: configuration.embedding_connect_timeout,
           read_timeout: configuration.embedding_read_timeout
@@ -66,17 +109,13 @@ module Jekyll
         documents.each { |document| document.delete("embedding") }
       end
 
-      def embed_document(document, cache, adapter, configuration)
-        hash = IndexCache.content_hash(document)
-        cached = cache.lookup(document["id"], hash)
-        if cached && cached["embedding"]
-          document["embedding"] = cached["embedding"]
-          return
-        end
+      def embed_document(document, cache, adapter, configuration, job)
+        hash = IndexCache.content_hash(document.except("embedding", "related_embedding"))
+        return if embedding_restored?(document, cache, hash, job[:field])
 
-        embedding = adapter.embed(embedding_text(document, configuration))
+        embedding = adapter.embed(embedding_text(document, job[:document_prefix]))
         if embedding
-          document["embedding"] = embedding
+          document[job[:field]] = embedding
           cache.store(document["id"], hash, embedding)
         elsif configuration.embedding_fail_on_error?
           raise Jekyll::Errors::FatalException,
@@ -84,9 +123,17 @@ module Jekyll
         end
       end
 
-      def embedding_text(document, configuration)
+      def embedding_restored?(document, cache, hash, field)
+        cached = cache.lookup(document["id"], hash)
+        return false unless cached && cached["embedding"]
+
+        document[field] = cached["embedding"]
+        true
+      end
+
+      def embedding_text(document, document_prefix)
         text = [document["title"], document["excerpt"], document["content"]].compact.join(" ")
-        "#{configuration.embedding_document_prefix}#{text}"
+        "#{document_prefix}#{text}"
       end
 
       def collection_documents(site, configuration, builder)

data/lib/jekyll/client_search/index_cache.rb

@@ -12,11 +12,12 @@ module Jekyll
     # should be git-ignored.
     class IndexCache
       CACHE_FILE = ".jekyll-client-search-cache.json"
+      RELATED_CACHE_FILE = ".jekyll-client-search-related-cache.json"
 
       attr_reader :path
 
-      def initialize(site_source, embedding_identity: nil)
-        @path = File.join(site_source, CACHE_FILE)
+      def initialize(site_source, embedding_identity: nil, file_name: CACHE_FILE)
+        @path = File.join(site_source, file_name)
         @embedding_identity = embedding_identity
         @entries = load
       end

data/lib/jekyll/client_search/ollama_embedding_adapter.rb

@@ -11,6 +11,11 @@ module Jekyll
     #     enabled: true
     #     model: all-minilm          # or nomic-embed-text, bge-m3, etc.
     #     base_url: http://localhost:11434
+    #
+    # A +localhost+ base_url is resolved once to the loopback literal
+    # (127.0.0.1 or ::1) that accepts a TCP connection, because Excon
+    # does not fall back across address families when the DNS name maps
+    # to a family the server is not listening on.
     class OllamaEmbeddingAdapter
       attr_reader :model, :base_url, :connect_timeout, :read_timeout
 
@@ -48,12 +53,53 @@ module Jekyll
         @client ||= begin
           require "ollama"
           Ollama::Client.new(
-            base_url: @base_url,
+            base_url: resolved_base_url,
             connect_timeout: @connect_timeout,
             read_timeout: @read_timeout
           )
         end
       end
+
+      # "localhost" may resolve to ::1 while the server only listens on
+      # 127.0.0.1, or the reverse. Excon does not fall back across
+      # address families, so probe both loopback literals once and use
+      # the one that accepts a TCP connection. Any other host name is
+      # used exactly as configured.
+      def resolved_base_url
+        @resolved_base_url ||= resolve_localhost(@base_url)
+      end
+
+      def resolve_localhost(base_url)
+        require "uri"
+        uri = URI.parse(base_url)
+        return base_url unless uri.host.to_s.chomp(".").casecmp("localhost").zero?
+
+        resolved = loopback_base_url(uri)
+        return base_url unless resolved
+
+        Jekyll.logger.info "ClientSearch:", "resolved localhost to #{resolved}"
+        resolved
+      rescue URI::InvalidURIError
+        base_url
+      end
+
+      def loopback_base_url(uri)
+        %w[127.0.0.1 ::1].each do |address|
+          next unless tcp_reachable?(address, uri.port)
+
+          resolved = uri.dup
+          resolved.host = address.include?(":") ? "[#{address}]" : address
+          return resolved.to_s
+        end
+        nil
+      end
+
+      def tcp_reachable?(address, port)
+        require "socket"
+        Socket.tcp(address, port, connect_timeout: @connect_timeout) { true }
+      rescue SystemCallError, SocketError
+        false
+      end
     end
   end
 end

data/lib/jekyll/client_search/query_embedder_configuration.rb

@@ -8,6 +8,9 @@ module Jekyll
 
       MODEL_MAP = {
         "embeddinggemma:300m" => "onnx-community/embeddinggemma-300m-ONNX",
+        "embeddinggemma-2" => "onnx-community/embeddinggemma-2-ONNX",
+        "embeddinggemma-2:270m" => "onnx-community/embeddinggemma-2-ONNX",
+        "embeddinggemma-2:570m" => "onnx-community/embeddinggemma-2-ONNX",
         "all-minilm" => "Xenova/all-MiniLM-L6-v2"
       }.freeze
 

data/lib/jekyll/client_search/related_analyzer.rb

@@ -29,7 +29,10 @@ module Jekyll
 
       def build_relation(source, target)
         metadata = metadata_relation(source, target)
-        semantic_similarity = similarity(source["embedding"], target["embedding"])
+        semantic_similarity = similarity(
+          source["related_embedding"] || source["embedding"],
+          target["related_embedding"] || target["embedding"]
+        )
         return unless metadata || semantic_match?(semantic_similarity)
 
         relation = base_relation(target, metadata, semantic_similarity)