jekyll-client-search 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 770d678df814030f4576214a39a7faca03f14d889cc284c5976486bc7c22f331
-  data.tar.gz: 2eaf824353f2b981ec1c538c3a84b938198960d1092110b6efceb181311ce2ea
+  metadata.gz: ed1c7a635cc419d9fb130411ced8e64a473c016e8188e36ddd98ea6922a098f7
+  data.tar.gz: f320844ded59274df991b1aa3d56fb22560e818105c5a0e682ea6e6a0c67df88
 SHA512:
-  metadata.gz: 44e285f7238df3e68523839fb80bdc3f67c25883e3311753b8b67d460a160dcb7e1b9c3c23c9066e04dc57b7d2e951924ebfc55ba205b4913e882b764e0fbff3
-  data.tar.gz: e9b48c426a74311b235b33eda93d119ba3864be6d64175640de6971521461226baf5f8c5e88e89a47889beea28feae22833d3ec49a8cf461064e8e7101fab1fc
+  metadata.gz: a12fb0052f9a727baf957735cd23fc9759f46fe7b54977acd16ed63edb14b0d63e2594d3c2bee936c9317541f8810a654acf7a5369746c9d11c39699457cf351
+  data.tar.gz: 46986b4c1a0107821f6932d8538c1aff0fcc386ddb9e9f787a4890da5f8af3ccd30a8c0b6b9257d928d3b52aa6fe625806136812cfbf781763a0f3a391cf9aa6

data/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 0.3.0 — 2026-09-02
+
+### Added
+- `{% search_dropdown %}` Liquid tag — compact live-search dropdown for navbars and headers with keyboard navigation (Arrow/Enter/Escape), lazy index loading, icon support, and framework-agnostic semantic HTML (no Bulma/Bootstrap/Tailwind classes)
+- `DropdownConfiguration` class with `enabled`, `max_items`, `min_chars`, `debounce_ms`, `redirect_url` options
+- `assets/client-search-dropdown.js` runtime (434 lines) — two-stage search (AND first, fuzzy OR fallback), shared index cache with the base runtime, multi-instance support via `[data-client-search-dropdown]` attributes, icon rendering from `icon_field`
+- `max:N` parameter on `{% related_articles %}` tag (e.g. `{% related_articles max:3 %}`, `{% related_articles sort:date max:10 %}`)
+- `max_items` config option for `related` section (default: 5)
+- Dropdown config included in generated `search-runtime-config.js`
+- `dropdown_enabled?` accessor and dropdown asset in `runtime_assets`
+- HTML-escaping (via `CGI.escapeHTML`) for `engine_url`, `engine_sri`, and `engine_crossorigin` attributes in `SearchTag` script output
+- Defensive guard with `simplecov:disable` annotation for unreachable `embedder_asset` nil branch in `SearchTag`
+- Ollama embedding adapter tests for empty/invalid responses and standard error handling
+- Related analyzer tests for semantic-only similarity matching
+- System test assertions for embeddings/retrieval content matching and non-ASCII query robustness
+
+### Changed
+- `related.max_items` default changed from `nil` (unlimited) to `5`
+- `Configuration#initialize` refactored — extracted `normalize_configured` helper for cleaner config validation
+- Runtime config page now merges `dropdown` config alongside `liveSearch`
+- `SearchTag` and `RelatedTag` now return empty string when `site` is nil or `client_search` is `false` (previously crashed on nil site)
+- Meta test (`test/meta.test.js`) converted from `forEach` to `for` loops to properly `await` settle in cross-engine comparison
+- System tests strengthened with content assertions and non-ASCII robustness checks
+- AGENTS.md restructured — split developer info to README.developer.md, added dropdown architecture entries
+- README.developer.md expanded with coverage documentation, spec file table, and SimpleCov branch coverage notes
+- README.md updated with dropdown section, related `max:N` docs, and CSS styling examples for dropdown
+
+### Fixed
+- `SearchTag#render` no longer raises on nil site (now returns empty string)
+- `RelatedTag#render` no longer raises on nil site or `client_search: false` config
+- Meta test race condition — `forEach` callback couldn't `await settle()`, causing flaky cross-engine comparisons; fixed by switching to `for` loops
+
 ## 0.2.0 — 2026-08-27
 
 ### Added

data/README.developer.md

@@ -12,8 +12,9 @@ rbenv install 3.4.10       # if not already installed
 rbenv local 3.4.10
 bundle install
 npm ci
-bundle exec rspec          # Ruby tests (176 examples; 7 opt-in Ollama examples pending)
-npm test                   # JavaScript tests (130 tests)
+bundle exec rspec                          # Ruby tests (248 examples; 7 Ollama pending)
+OLLAMA_INTEGRATION=1 bundle exec rspec     # all tests including Ollama integration
+npm test                                   # JavaScript tests (134 tests)
 ```
 
 Both test suites pass with only the committed Wikipedia fixtures and the
@@ -113,14 +114,9 @@ content, self-exclusion, and score sorting.
 
 ### Related test files
 
-| File | Description |
-| --- | --- |
-| `spec/related_analyzer_spec.rb` | Unit tests for the relation analyzer |
-| `spec/related_tag_spec.rb` | Unit tests for the `{% related_articles %}` Liquid tag |
-| `spec/search_tag_spec.rb` | Unit tests for the `{% search_form %}` Liquid tag |
-| `spec/tasks_spec.rb` | Unit tests for the rake tasks (reference_files, install) |
-| `spec/system_spec.rb` | System tests building the fixture site with related and search_form |
-| `test/related.test.js` | JS tests for the related renderer (default, renderItem, filter, sort) |
+See the [Spec files](#spec-files) table for the full list. The key related
+test files are `spec/related_analyzer_spec.rb`, `spec/related_tag_spec.rb`,
+`spec/system_spec.rb`, and `test/related.test.js`.
 
 ## What is committed
 
@@ -248,6 +244,72 @@ bundle exec rspec --tag system
 bundle exec rspec --tag ollama_integration
 ```
 
+## Coverage
+
+The project uses SimpleCov 1.1+ with branch coverage. The target is 100%
+branch coverage and ~99.6% line coverage. Three lines are intentionally
+excluded via `# simplecov:disable branch` for an unreachable defensive
+guard in `search_tag.rb` (the `if embedder_asset` check that can never be
+false with current embedder types — `semantic_with_embedder?` already
+filters out the `none` type, and both `transformers` and `ollama_api`
+always return an asset).
+
+The coverage report is generated at `coverage/index.html` after each RSpec
+run. Raw data is in `coverage/.resultset.json` (SimpleCov 1.0+ format with
+`lines` and `branches` keys per file).
+
+To check remaining uncovered lines and branches after a run:
+
+```bash
+python3 -c "
+import json
+with open('coverage/.resultset.json') as f:
+    data = json.load(f)
+for suite, info in data.items():
+    cov = info.get('coverage', {})
+    for file, lines in sorted(cov.items()):
+        if 'lib/jekyll' not in file: continue
+        short = file.split('/lib/')[-1]
+        line_data = lines.get('lines', []) if isinstance(lines, dict) else lines
+        uncovered = [i+1 for i, v in enumerate(line_data) if v == 0]
+        if uncovered:
+            print(f'{short}: lines {uncovered}')
+        branches = lines.get('branches', {}) if isinstance(lines, dict) else {}
+        for bk, bd in branches.items():
+            for sk, count in bd.items():
+                if count == 0:
+                    print(f'{short}: {sk} (count=0)')
+"
+```
+
+## Spec files
+
+| File | Description |
+| --- | --- |
+| `spec/configuration_spec.rb` | Site configuration, defaults, validation |
+| `spec/dropdown_configuration_spec.rb` | Dropdown config validation |
+| `spec/dropdown_tag_spec.rb` | `{% search_dropdown %}` Liquid tag |
+| `spec/search_tag_spec.rb` | `{% search_form %}` Liquid tag |
+| `spec/related_tag_spec.rb` | `{% related_articles %}` Liquid tag |
+| `spec/related_analyzer_spec.rb` | Build-time relation analysis |
+| `spec/related_configuration_spec.rb` | Related config validation |
+| `spec/generator_spec.rb` | Jekyll generator integration |
+| `spec/document_builder_spec.rb` | Normalized search documents |
+| `spec/search_index_page_spec.rb` | Generated JSON page |
+| `spec/index_cache_spec.rb` | Index cache |
+| `spec/embedding_cache_spec.rb` | Embedding cache |
+| `spec/runtime_assets_spec.rb` | Runtime asset copying |
+| `spec/runtime_config_page_spec.rb` | Runtime config page generation |
+| `spec/ollama_embedding_adapter_spec.rb` | Ollama adapter unit tests |
+| `spec/ollama_integration_spec.rb` | Ollama integration tests (pending) |
+| `spec/llm_injection_spec.rb` | LLM injection baseline tests (pending) |
+| `spec/tasks_spec.rb` | Rake tasks (reference_files, install) |
+| `spec/gemspec_spec.rb` | Gemspec metadata |
+| `spec/system_spec.rb` | End-to-end system tests |
+| `test/runtime.test.js` | JS unit tests parameterized over adapters |
+| `test/related.test.js` | JS tests for related renderer |
+| `test/system.test.js` | JS system tests using committed baseline index |
+
 ## CI
 
 The CI pipeline runs `bundle exec rspec` and `npm test` without arXiv

data/README.md

@@ -25,6 +25,7 @@ and vector similarity.
   - [Related articles](#related-articles)
   - [Semantic search (embeddings)](#semantic-search-embeddings)
 - [The search form](#the-search-form)
+- [The search dropdown](#the-search-dropdown)
 - [Rake tasks](#rake-tasks)
 - [Configuration reference](#configuration-reference)
 - [Indexing custom collections](#indexing-custom-collections)
@@ -139,6 +140,23 @@ Then add one line to any post layout:
 {% related_articles %}
 ```
 
+By default, 5 related articles are shown. Override per-tag with `max:N`:
+
+```liquid
+{% related_articles max:3 %}
+{% related_articles sort:date max:10 %}
+```
+
+Or set the default in `_config.yml`:
+
+```yaml
+client_search:
+  related:
+    enabled: true
+    max_items: 5           # default: 5; null = no limit
+    minimum_similarity: 0.55
+```
+
 Without embeddings, relations are based on shared tags, categories, and
 hierarchical parent domains. With embeddings enabled, vector similarity
 above the cutoff is also included. See
@@ -216,6 +234,77 @@ client_search:
 For manual `<script>` setup (engine-specific HTML), see
 [Browser usage reference](#browser-usage-reference).
 
+## The search dropdown
+
+The `{% search_dropdown %}` Liquid tag renders a compact live-search
+dropdown suitable for navbars and headers. It is framework-agnostic —
+emits semantic HTML with data attributes, no CSS classes from Bulma,
+Bootstrap, Tailwind, or any other framework. Style it with your own CSS.
+
+```liquid
+{% search_dropdown %}
+```
+
+Tag modes:
+
+| Syntax | Effect |
+| --- | --- |
+| `{% search_dropdown %}` | Dropdown HTML + all scripts (default) |
+| `{% search_dropdown max:10 %}` | Show up to 10 items (default: 5) |
+| `{% search_dropdown scripts_only %}` | Just the scripts — use with custom HTML |
+| `{% search_dropdown no_scripts %}` | Just the dropdown HTML — load scripts yourself |
+
+**Behavior:**
+
+- User types → results appear in a dropdown list (live, debounced)
+- Enter with no item selected → redirect to `redirect_url` (default
+  `/search/`) with `?q=...` for full results on the search page
+- Arrow Up/Down → highlight items, Enter on highlighted → navigate
+- Click an item → navigate to that document's URL
+- Escape or click outside → close dropdown
+- Index is lazy-loaded on first keystroke (no cost on pages where the
+  visitor doesn't search)
+
+**Configuration:**
+
+```yaml
+client_search:
+  dropdown:
+    enabled: true          # default
+    max_items: 5           # default, tag param max:N overrides
+    min_chars: 2           # minimum query length before search fires
+    debounce_ms: 150       # debounce delay
+    redirect_url: /search/ # where Enter redirects for full results
+```
+
+**Icon support:** When `icon_field` is configured (default `icon_url`)
+and the search index includes that field (e.g. from jekyll-documents),
+an `<img>` icon is rendered before each result title. Set `icon_field:
+null` to disable.
+
+**CSS styling:** The dropdown emits no framework classes. Style with:
+
+```css
+.client-search-dropdown { position: relative; }
+.client-search-dropdown ul[role="listbox"] {
+  position: absolute; top: 100%; right: 0;
+  min-width: 300px; z-index: 30;
+  background: white; box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+  list-style: none; margin: 0; padding: 0;
+}
+.client-search-dropdown li { padding: 0.5rem 1rem; }
+.client-search-dropdown li:hover,
+.client-search-dropdown li[aria-selected="true"] { background: #f5f5f5; }
+.client-search-dropdown li a { text-decoration: none; color: inherit; }
+
+/* Type-based styling via data attributes */
+.client-search-dropdown li[data-source="documents"] { border-left: 3px solid #48c774; }
+.client-search-dropdown li[data-file-type="pdf"]::before {
+  content: "PDF"; background: #ff0000; color: white;
+  padding: 0 0.3em; font-size: 0.7em; margin-right: 0.3em;
+}
+```
+
 ### Customizing search results with CSS
 
 Each search result is rendered as an `<article>` with data attributes that
@@ -663,10 +752,16 @@ must return a DOM node (or `null` to skip the item):
 <script src="/assets/client-search-related.js"></script>
 <script>
   ClientSearchRelated.run({
-    renderItem: function (item, document) {
-      var li = document.createElement("li");
-      li.innerHTML = '<a href="' + item.url + '">' + item.title + "</a>" +
-        '<span class="score">' + (item.score * 100).toFixed(0) + "%</span>";
+    renderItem: function (item, dom) {
+      var li = dom.createElement("li");
+      var link = dom.createElement("a");
+      link.href = item.url;
+      link.textContent = item.title;
+      var score = dom.createElement("span");
+      score.className = "score";
+      score.textContent = (item.score * 100).toFixed(0) + "%";
+      li.appendChild(link);
+      li.appendChild(score);
       return li;
     }
   });

data/assets/client-search-dropdown.js

@@ -0,0 +1,434 @@
+(function () {
+    "use strict";
+
+    /**
+     * ClientSearch dropdown runtime — compact live-search dropdown for
+     * navbars and headers. Framework-agnostic: emits semantic HTML with
+     * data attributes, no CSS classes from any framework.
+     *
+     * 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)
+     *   - Enter with no selection → redirect to redirect_url (?q=...)
+     *   - Click outside or Escape → close dropdown
+     *   - Multi-instance via [data-client-search-dropdown] attributes
+     *   - Shared index cache with the base runtime when present
+     */
+
+    var sharedIndex = null;
+    var sharedDocuments = null;
+    var indexLoadPromise = null;
+
+    function safeUrl(value) {
+        if (value === "#") {
+            return "#";
+        }
+        try {
+            var url = new URL(value, window.location.origin);
+            if (url.origin === window.location.origin &&
+                ["http:", "https:"].includes(url.protocol)) {
+                return url.pathname + url.search + url.hash;
+            }
+        } catch (_error) {
+            return "#";
+        }
+        return "#";
+    }
+
+    function toCamelCase(key) {
+        return key.replace(/_([a-z])/g, function (_, char) { return char.toUpperCase(); });
+    }
+
+    function normalize(entry) {
+        var id = entry.id || entry.url;
+        if (!id) {
+            return null;
+        }
+        var categories = Array.isArray(entry.categories) ? entry.categories : [];
+        var tags = Array.isArray(entry.tags) ? entry.tags : [];
+        var normalized = {
+            id: id,
+            title: entry.title || "Untitled",
+            url: entry.url || "#",
+            excerpt: entry.excerpt || "",
+            content: entry.content || "",
+            date: entry.date || "",
+            date_timestamp: Number(entry.date_timestamp) || 0,
+            categories: categories,
+            tags: tags,
+            categoriesText: categories.join(" "),
+            tagsText: tags.join(" ")
+        };
+        if (entry.source) {
+            normalized.source = entry.source;
+        }
+        Object.keys(entry).forEach(function (key) {
+            if (!(key in normalized) && key !== "embedding") {
+                var value = entry[key];
+                if (value !== null && value !== undefined && value !== "") {
+                    normalized[key] = value;
+                }
+            }
+        });
+        return normalized;
+    }
+
+    function loadIndex(config) {
+        if (sharedIndex && sharedDocuments) {
+            return Promise.resolve({ index: sharedIndex, documents: sharedDocuments });
+        }
+        if (indexLoadPromise) {
+            return indexLoadPromise;
+        }
+
+        var indexUrl = config.indexUrl;
+        if (!indexUrl) {
+            return Promise.reject(new Error("No index URL configured"));
+        }
+
+        indexLoadPromise = fetch(indexUrl, { headers: { Accept: "application/json" } })
+            .then(function (response) {
+                if (!response.ok) {
+                    throw new Error("Unable to load search index");
+                }
+                return response.json();
+            })
+            .then(function (data) {
+                if (!Array.isArray(data)) {
+                    throw new TypeError("Search index must be an array");
+                }
+                var documents = data.map(normalize).filter(Boolean);
+                var adapter = window.ClientSearchAdapters &&
+                    (window.ClientSearchAdapters[config.engine] ||
+                     window.ClientSearchAdapters.minisearch);
+                if (!adapter) {
+                    throw new Error("Search adapter not loaded");
+                }
+                sharedDocuments = new Map(documents.map(function (entry) {
+                    return [entry.id, entry];
+                }));
+                sharedIndex = adapter.buildIndex(documents);
+                return { index: sharedIndex, documents: sharedDocuments };
+            })
+            .catch(function (error) {
+                indexLoadPromise = null;
+                throw error;
+            });
+
+        return indexLoadPromise;
+    }
+
+    function search(index, query, adapter) {
+        var exact = adapter.search(index, query, {
+            combineWith: "AND",
+            fuzzy: false,
+            prefix: true
+        });
+        if (exact && typeof exact.then === "function") {
+            return exact.then(function (results) {
+                if (results && results.length > 0) {
+                    return results;
+                }
+                return adapter.search(index, query, {
+                    combineWith: "OR",
+                    fuzzy: true,
+                    prefix: true
+                });
+            });
+        }
+        if (exact && exact.length > 0) {
+            return exact;
+        }
+        return adapter.search(index, query, {
+            combineWith: "OR",
+            fuzzy: true,
+            prefix: true
+        });
+    }
+
+    function createResultItem(match, documents, iconField) {
+        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);
+
+        if (entry.source) {
+            li.dataset.source = entry.source;
+        }
+        if (entry.categories && entry.categories.length) {
+            li.dataset.categories = entry.categories.join(" ");
+        }
+        if (entry.tags && entry.tags.length) {
+            li.dataset.tags = entry.tags.join(" ");
+        }
+        Object.keys(entry).forEach(function (key) {
+            var skip = ["id", "title", "url", "excerpt", "content",
+                "categories", "tags", "source", "embedding",
+                "date_timestamp"];
+            if (skip.indexOf(key) !== -1) {
+                return;
+            }
+            var value = entry[key];
+            if (typeof value === "string" || typeof value === "number") {
+                li.dataset[toCamelCase(key)] = String(value);
+            }
+        });
+
+        if (iconField && entry[iconField]) {
+            var icon = document.createElement("img");
+            icon.className = "client-search-dropdown-icon";
+            icon.src = safeUrl(entry[iconField]);
+            icon.alt = entry.file_type || entry.source || "";
+            icon.loading = "lazy";
+            icon.style.width = "1em";
+            icon.style.height = "1em";
+            icon.style.verticalAlign = "middle";
+            icon.style.marginRight = "0.3em";
+            li.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);
+
+        return li;
+    }
+
+    function DropdownInstance(root, config) {
+        this.root = root;
+        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.config = config;
+        this.maxItems = parseInt(this.results.dataset.maxItems, 10) || config.maxItems || 5;
+        this.selectedIndex = -1;
+        this.currentItems = [];
+        this.debounceTimer = null;
+        this.renderVersion = 0;
+        this.adapter = null;
+    }
+
+    DropdownInstance.prototype.init = function () {
+        if (!this.form || !this.input || !this.results) {
+            return;
+        }
+
+        var self = this;
+
+        this.input.addEventListener("input", function () {
+            self.onInput();
+        });
+
+        this.input.addEventListener("keydown", function (event) {
+            self.onKeydown(event);
+        });
+
+        this.form.addEventListener("submit", function (event) {
+            event.preventDefault();
+            self.onSubmit();
+        });
+
+        document.addEventListener("click", function (event) {
+            if (!self.root.contains(event.target)) {
+                self.hide();
+            }
+        });
+
+        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;
+            }
+        });
+    };
+
+    DropdownInstance.prototype.onInput = function () {
+        var self = this;
+        this.renderVersion += 1;
+        clearTimeout(this.debounceTimer);
+
+        var query = this.input.value.trim();
+        if (!query || query.length < this.config.minChars) {
+            this.hide();
+            return;
+        }
+
+        this.debounceTimer = setTimeout(function () {
+            self.performSearch(query);
+        }, this.config.debounceMs);
+    };
+
+    DropdownInstance.prototype.onKeydown = function (event) {
+        if (this.results.getAttribute("aria-hidden") === "true") {
+            return;
+        }
+        var visible = this.results.children.length > 0;
+        if (!visible) {
+            return;
+        }
+
+        switch (event.key) {
+            case "ArrowDown":
+                event.preventDefault();
+                this.selectItem(Math.min(this.selectedIndex + 1, this.currentItems.length - 1));
+                break;
+            case "ArrowUp":
+                event.preventDefault();
+                this.selectItem(Math.max(this.selectedIndex - 1, 0));
+                break;
+            case "Enter":
+                if (this.selectedIndex >= 0 && this.currentItems[this.selectedIndex]) {
+                    event.preventDefault();
+                    var url = this.currentItems[this.selectedIndex].dataset.url;
+                    if (url && url !== "#") {
+                        window.location.href = url;
+                    }
+                }
+                break;
+            case "Escape":
+                this.hide();
+                this.input.blur();
+                break;
+            case "Tab":
+                this.hide();
+                break;
+        }
+    };
+
+    DropdownInstance.prototype.onSubmit = function () {
+        var query = this.input.value.trim();
+        if (!query) {
+            return;
+        }
+        var redirectUrl = this.config.redirectUrl || "/search/";
+        var separator = redirectUrl.indexOf("?") !== -1 ? "&" : "?";
+        window.location.href = redirectUrl + separator + "q=" + encodeURIComponent(query);
+    };
+
+    DropdownInstance.prototype.performSearch = function (query) {
+        var self = this;
+        var version = this.renderVersion;
+
+        var config = this.config;
+        var engineName = config.engine || "minisearch";
+
+        loadIndex(config).then(function (loaded) {
+            if (version !== self.renderVersion) {
+                return;
+            }
+
+            var adapter = window.ClientSearchAdapters &&
+                (window.ClientSearchAdapters[engineName] ||
+                 window.ClientSearchAdapters.minisearch);
+            if (!adapter || !adapter.available()) {
+                return;
+            }
+
+            var results = search(loaded.index, query, adapter);
+            return Promise.resolve(results).then(function (matches) {
+                if (version === self.renderVersion) {
+                    self.renderResults(matches, loaded.documents);
+                }
+            });
+        }).catch(function () {
+            if (version === self.renderVersion) {
+                self.hide();
+            }
+        });
+    };
+
+    DropdownInstance.prototype.renderResults = function (matches, documents) {
+        this.results.replaceChildren();
+        this.currentItems = [];
+        this.selectedIndex = -1;
+
+        if (!matches || matches.length === 0) {
+            this.hide();
+            return;
+        }
+
+        var iconField = this.config.iconField || null;
+        var count = Math.min(matches.length, this.maxItems);
+
+        for (var i = 0; i < count; i++) {
+            var item = createResultItem(matches[i], documents, iconField);
+            if (item) {
+                this.results.appendChild(item);
+                this.currentItems.push(item);
+            }
+        }
+
+        if (this.currentItems.length === 0) {
+            this.hide();
+            return;
+        }
+
+        this.show();
+    };
+
+    DropdownInstance.prototype.selectItem = function (index) {
+        this.selectedIndex = index;
+        for (var i = 0; i < this.currentItems.length; i++) {
+            if (i === index) {
+                this.currentItems[i].setAttribute("aria-selected", "true");
+            } else {
+                this.currentItems[i].removeAttribute("aria-selected");
+            }
+        }
+        if (this.currentItems[index]) {
+            this.currentItems[index].scrollIntoView({ block: "nearest" });
+        }
+    };
+
+    DropdownInstance.prototype.show = function () {
+        this.results.setAttribute("aria-hidden", "false");
+        this.input.setAttribute("aria-expanded", "true");
+    };
+
+    DropdownInstance.prototype.hide = function () {
+        this.results.setAttribute("aria-hidden", "true");
+        this.input.setAttribute("aria-expanded", "false");
+        this.results.replaceChildren();
+        this.currentItems = [];
+        this.selectedIndex = -1;
+    };
+
+    function initAll() {
+        var config = window.clientSearchConfig || {};
+        var dropdownConfig = config.dropdown || {};
+        if (dropdownConfig.enabled === false) {
+            return;
+        }
+
+        var mergedConfig = {
+            indexUrl: config.indexUrl,
+            engine: config.engine || "minisearch",
+            iconField: config.iconField || null,
+            minChars: typeof dropdownConfig.minChars === "number" ? dropdownConfig.minChars : 2,
+            debounceMs: typeof dropdownConfig.debounceMs === "number" ? dropdownConfig.debounceMs : 150,
+            maxItems: typeof dropdownConfig.maxItems === "number" ? dropdownConfig.maxItems : 5,
+            redirectUrl: dropdownConfig.redirectUrl || "/search/"
+        };
+
+        var roots = document.querySelectorAll("[data-client-search-dropdown]");
+        roots.forEach(function (root) {
+            var instance = new DropdownInstance(root, mergedConfig);
+            instance.init();
+        });
+    }
+
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", initAll);
+    } else {
+        initAll();
+    }
+}());

data/assets/client-search-related.js

@@ -100,6 +100,11 @@
         }
         sortItems(items, sortOrder);
 
+        var maxItems = options.maxItems || 0;
+        if (maxItems && maxItems > 0) {
+            items = items.slice(0, maxItems);
+        }
+
         container.replaceChildren();
         if (items.length === 0) {
             return;
@@ -138,6 +143,7 @@
                 relationsUrl: window.clientSearchConfig && window.clientSearchConfig.relatedUrl,
                 currentUrl: window.location.pathname,
                 sort: (window.clientSearchConfig && window.clientSearchConfig.relatedSort) || "relevance",
+                maxItems: 0,
                 renderItem: null,
                 filter: null
             }, options || {});
@@ -146,6 +152,10 @@
                 return Promise.resolve();
             }
 
+            if (container.dataset.relatedMax) {
+                options.maxItems = parseInt(container.dataset.relatedMax, 10) || 0;
+            }
+
             return fetch(options.relationsUrl, { headers: { Accept: "application/json" } })
                 .then(function (response) {
                     if (!response.ok) {

data/lib/jekyll/client_search/configuration.rb

@@ -39,17 +39,11 @@ module Jekyll
       }.freeze
 
       def initialize(site)
-        configured = site.config["client_search"]
-        configured = { "enabled" => false } if configured == false
-        configured ||= {}
-        unless configured.is_a?(Hash)
-          raise Jekyll::Errors::FatalException,
-                "client_search configuration must be a mapping or false"
-        end
-
+        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"] || {})
         merge_embedding_config(configured["embedding"])
         validate_engine!
         return unless embedding_enabled?
@@ -60,6 +54,15 @@ module Jekyll
 
       private
 
+      def normalize_configured(value)
+        return { "enabled" => false } if value == false
+        return value if value.is_a?(Hash)
+        return {} if value.nil?
+
+        raise Jekyll::Errors::FatalException,
+              "client_search configuration must be a mapping or false"
+      end
+
       def merge_embedding_config(configured_embedding)
         embedding = configured_embedding || {}
         unless embedding.is_a?(Hash)
@@ -105,6 +108,7 @@ module Jekyll
         assets = ["assets/client-search-base.js", "assets/adapters/#{engine}.js"]
         assets.concat(query_embedder_assets) if engine == "semantic" && embedding_enabled?
         assets << "assets/client-search-related.js" if related_enabled?
+        assets << "assets/client-search-dropdown.js" if dropdown_enabled?
         assets
       end
 

data/lib/jekyll/client_search/configuration_accessors.rb

@@ -28,10 +28,6 @@ module Jekyll
         @query_embedder.model
       end
 
-      def query_embedder_api_url
-        @query_embedder.api_url
-      end
-
       def query_embedder_asset
         @query_embedder.asset
       end
@@ -43,6 +39,18 @@ module Jekyll
       def query_embedder_config_json
         @query_embedder.to_json
       end
+
+      def dropdown_enabled?
+        @dropdown.enabled?
+      end
+
+      def dropdown_max_items
+        @dropdown.max_items
+      end
+
+      def dropdown_config
+        @dropdown.to_h
+      end
     end
   end
 end

data/lib/jekyll/client_search/dropdown_configuration.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Jekyll
+  module ClientSearch
+    # Validates optional compact dropdown live-search settings.
+    class DropdownConfiguration
+      DEFAULTS = {
+        "enabled" => true,
+        "max_items" => 5,
+        "min_chars" => 2,
+        "debounce_ms" => 150,
+        "redirect_url" => "/search/"
+      }.freeze
+
+      def initialize(config)
+        unless config.is_a?(Hash)
+          raise Jekyll::Errors::FatalException,
+                "client_search dropdown configuration must be a mapping"
+        end
+
+        @values = DEFAULTS.merge(config)
+        validate!
+      end
+
+      def enabled?
+        @values.fetch("enabled") != false
+      end
+
+      def max_items
+        @values.fetch("max_items")
+      end
+
+      def min_chars
+        @values.fetch("min_chars")
+      end
+
+      def debounce_ms
+        @values.fetch("debounce_ms")
+      end
+
+      def redirect_url
+        @values.fetch("redirect_url").to_s
+      end
+
+      def to_h
+        {
+          "enabled" => enabled?,
+          "maxItems" => max_items,
+          "minChars" => min_chars,
+          "debounceMs" => debounce_ms,
+          "redirectUrl" => redirect_url
+        }
+      end
+
+      private
+
+      def validate!
+        validate_boolean!("enabled")
+        validate_integer!("max_items", minimum: 1)
+        validate_integer!("min_chars", minimum: 0)
+        validate_integer!("debounce_ms", minimum: 0)
+        if redirect_url.empty?
+          raise Jekyll::Errors::FatalException,
+                "client_search dropdown redirect_url must not be empty"
+        end
+
+        uri = URI.parse(redirect_url)
+        return if uri.scheme.nil? && uri.host.nil? && !redirect_url.start_with?("//")
+
+        raise Jekyll::Errors::FatalException,
+              "client_search dropdown redirect_url must be a relative path"
+      end
+
+      def validate_boolean!(key)
+        return if [true, false].include?(@values[key])
+
+        raise Jekyll::Errors::FatalException,
+              "client_search dropdown.#{key} must be true or false"
+      end
+
+      def validate_integer!(key, minimum:)
+        value = @values.fetch(key)
+        return if value.is_a?(Integer) && value >= minimum
+
+        raise Jekyll::Errors::FatalException,
+              "client_search dropdown.#{key} must be an integer greater than or equal to #{minimum}"
+      end
+    end
+  end
+end

data/lib/jekyll/client_search/dropdown_tag.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Jekyll
+  module ClientSearch
+    # Liquid tag that renders a compact live-search dropdown suitable for
+    # navbars and headers. Framework-agnostic — emits semantic HTML with
+    # data attributes, no CSS classes from any framework.
+    #
+    #   {% search_dropdown %}
+    #   {% search_dropdown max:10 %}
+    #   {% search_dropdown scripts_only %}
+    #   {% search_dropdown no_scripts %}
+    #
+    # When client_search is disabled the tag renders nothing.
+    class DropdownTag < Liquid::Tag
+      SYNTAX = /\A(max:(\d+))?\s*(scripts_only|no_scripts)?\z/
+
+      def initialize(tag_name, markup, tokens)
+        super
+        @markup = markup.to_s.strip
+        unless (match = @markup.match(SYNTAX))
+          raise Liquid::SyntaxError,
+                "search_dropdown: invalid syntax. Use {% search_dropdown %}, " \
+                "{% search_dropdown max:10 %}, {% search_dropdown scripts_only %}, " \
+                "or {% search_dropdown no_scripts %}"
+        end
+
+        @max_items = match[2].to_i if match[2]
+        raise Liquid::SyntaxError, "search_dropdown: max must be greater than zero" if @max_items && @max_items < 1
+
+        @mode = match[3] || "full"
+        @input_id = "cs-dropdown-input-#{object_id}"
+        @results_id = "cs-dropdown-results-#{object_id}"
+      end
+
+      def render(context)
+        site = context.registers[:site]
+        return "" unless enabled?(site)
+
+        configuration = Configuration.new(site)
+        return "" unless configuration.dropdown_enabled?
+
+        render_mode(configuration, site)
+      end
+
+      private
+
+      def enabled?(site)
+        return false if site.nil?
+
+        config_hash = site.config.fetch("client_search", {})
+        config_hash != false && config_hash["enabled"] != false
+      end
+
+      def render_mode(configuration, site)
+        baseurl = site.config["baseurl"].to_s.gsub(%r{\A/+|/+$}, "")
+        prefix = baseurl.empty? ? "" : "/#{baseurl}"
+        max = resolve_max(configuration)
+
+        form_html = build_form(max)
+        return form_html if @mode == "no_scripts"
+
+        scripts = build_scripts(configuration, prefix)
+        return scripts if @mode == "scripts_only"
+
+        "#{form_html}\n#{scripts}"
+      end
+
+      def resolve_max(configuration)
+        @max_items || configuration.dropdown_max_items
+      end
+
+      def build_form(max)
+        <<~HTML
+          <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"
+                     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>
+        HTML
+      end
+
+      def build_scripts(configuration, prefix)
+        scripts = []
+        engine = configuration.engine_url
+        if engine
+          attrs = ["src=\"#{CGI.escapeHTML(engine)}\""]
+          if configuration.engine_crossorigin
+            crossorigin = CGI.escapeHTML(configuration.engine_crossorigin)
+            attrs << "crossorigin=\"#{crossorigin}\""
+          end
+          if configuration.engine_sri
+            integrity = CGI.escapeHTML(configuration.engine_sri)
+            attrs << "integrity=\"#{integrity}\""
+          end
+          scripts << "<script #{attrs.join(' ')}></script>"
+        end
+        scripts << "<script src=\"#{prefix}/assets/search-runtime-config.js\"></script>"
+        scripts << "<script src=\"#{prefix}/assets/client-search-dropdown.js\"></script>"
+        scripts << "<script src=\"#{prefix}/assets/adapters/#{configuration.engine}.js\"></script>"
+        scripts.map { |script| "  #{script}" }.join("\n")
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag("search_dropdown", Jekyll::ClientSearch::DropdownTag)

data/lib/jekyll/client_search/related_configuration.rb

@@ -12,7 +12,7 @@ module Jekyll
         "include_parent_domains" => true,
         "semantic" => true,
         "minimum_similarity" => 0.55,
-        "max_items" => nil
+        "max_items" => 5
       }.freeze
 
       def initialize(config)

data/lib/jekyll/client_search/related_tag.rb

@@ -7,12 +7,14 @@ module Jekyll
     #
     #   {% related_articles %}
     #   {% related_articles sort:date %}
+    #   {% related_articles max:3 %}
+    #   {% related_articles sort:date max:3 %}
     #   {% related_articles no_scripts %}
     #
     # When +related.enabled+ is false the tag renders nothing, so it is safe
     # to leave in a layout even when the feature is off.
     class RelatedTag < Liquid::Tag
-      SYNTAX = /\A(sort:(\w+))?\s*(no_scripts)?\z/
+      SYNTAX = /\A(sort:(\w+))?\s*(max:(\d+))?\s*(no_scripts)?\z/
 
       def initialize(tag_name, markup, tokens)
         super
@@ -20,22 +22,30 @@ module Jekyll
         unless (match = @markup.match(SYNTAX))
           raise Liquid::SyntaxError,
                 "related_articles: invalid syntax. Use {% related_articles %}, " \
-                "{% related_articles sort:date %}, or {% related_articles no_scripts %}"
+                "{% related_articles sort:date %}, {% related_articles max:3 %}, " \
+                "or {% related_articles no_scripts %}"
         end
 
         @sort = match[2] if match[2]
-        @include_scripts = match[3].nil?
+        @max_items = match[4].to_i if match[4]
+        raise Liquid::SyntaxError, "related_articles: max must be greater than zero" if @max_items && @max_items < 1
+
+        @include_scripts = match[5].nil?
       end
 
       def render(context)
         site = context.registers[:site]
-        config = site&.config&.fetch("client_search", {})
+        return "" if site.nil?
+
+        config = site.config.fetch("client_search", {})
+        return "" if config == false
         return "" unless related_enabled?(config)
 
         asset_prefix = asset_prefix(site)
         sort_attr = @sort ? " data-related-sort=\"#{@sort}\"" : ""
+        max_attr = resolve_max_attr(config)
         scripts = build_scripts(asset_prefix)
-        build_html(sort_attr, scripts)
+        build_html(sort_attr, max_attr, scripts)
       end
 
       private
@@ -57,7 +67,19 @@ module Jekyll
           "<script src=\"#{prefix}/assets/client-search-related.js\"></script>"
       end
 
-      def build_html(sort_attr, scripts)
+      def resolve_max_attr(config)
+        related = config.fetch("related", {})
+        max = if @max_items
+                @max_items
+              elsif related.key?("max_items")
+                related["max_items"]
+              else
+                5
+              end
+        max.nil? ? "" : " data-related-max=\"#{max}\""
+      end
+
+      def build_html(sort_attr, max_attr, scripts)
         <<~HTML
           <section class="related-articles-section">
             <label for="related-sort">Sort related articles</label>
@@ -65,7 +87,7 @@ module Jekyll
               <option value="relevance">Most related</option>
               <option value="date">Newest</option>
             </select>
-            <div id="related-articles"#{sort_attr}></div>
+            <div id="related-articles"#{sort_attr}#{max_attr}></div>
           </section>#{scripts}
         HTML
       end

data/lib/jekyll/client_search/runtime_config_page.rb

@@ -13,10 +13,13 @@ module Jekyll
         }
         defaults["relatedUrl"] = index_url(site, configuration.related_output) if configuration.related_enabled?
         defaults["iconField"] = configuration.runtime_icon_field if configuration.runtime_icon_field
+        defaults["dropdown"] = configuration.dropdown_config if configuration.dropdown_enabled?
         json = JSON.generate(defaults)
         self.content = "window.clientSearchConfig = (function (generated, existing) {" \
                        "var liveSearch = Object.assign({}, generated.liveSearch, existing.liveSearch || {});" \
-                       "return Object.assign(generated, existing, { liveSearch: liveSearch });" \
+                       "var dropdown = Object.assign({}, generated.dropdown, existing.dropdown || {});" \
+                       "return Object.assign(generated, existing, " \
+                       "{ liveSearch: liveSearch, dropdown: dropdown });" \
                        "}(#{json}, window.clientSearchConfig || {}));\n"
       end
 

data/lib/jekyll/client_search/search_tag.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "cgi"
+
 module Jekyll
   module ClientSearch
     # Liquid tag that renders the search form, status/results containers,
@@ -28,7 +30,10 @@ module Jekyll
 
       def render(context)
         site = context.registers[:site]
-        config_hash = site&.config&.fetch("client_search", {})
+        return "" if site.nil?
+
+        config_hash = site.config.fetch("client_search", {})
+        return "" if config_hash == false
         return "" unless config_hash["enabled"] != false
 
         configuration = Configuration.new(site)
@@ -73,9 +78,15 @@ module Jekyll
         url = configuration.engine_url
         return nil unless url
 
-        attrs = ["src=\"#{url}\""]
-        attrs << "crossorigin=\"#{configuration.engine_crossorigin}\"" if configuration.engine_crossorigin
-        attrs << "integrity=\"#{configuration.engine_sri}\"" if configuration.engine_sri
+        attrs = ["src=\"#{CGI.escapeHTML(url)}\""]
+        if configuration.engine_crossorigin
+          crossorigin = CGI.escapeHTML(configuration.engine_crossorigin)
+          attrs << "crossorigin=\"#{crossorigin}\""
+        end
+        if configuration.engine_sri
+          integrity = CGI.escapeHTML(configuration.engine_sri)
+          attrs << "integrity=\"#{integrity}\""
+        end
         "<script #{attrs.join(' ')}></script>"
       end
 
@@ -84,7 +95,13 @@ module Jekyll
 
         scripts = ["<script src=\"#{prefix}/assets/search-embedder-config.js\"></script>"]
         embedder_asset = configuration.query_embedder_asset
+        # simplecov:disable branch
+        # Defensive guard: semantic_with_embedder? already excludes the "none"
+        # type, and both "transformers" and "ollama_api" always return an asset.
+        # This branch is unreachable with current embedder types but protects
+        # against future types that may have no script asset.
         scripts << "<script src=\"#{prefix}/#{embedder_asset}\"></script>" if embedder_asset
+        # simplecov:enable branch
         scripts
       end
 

data/lib/jekyll/client_search/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module ClientSearch
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/jekyll/client_search.rb

@@ -9,6 +9,7 @@ require_relative "client_search/version"
 require_relative "client_search/embedding_configuration"
 require_relative "client_search/live_search_configuration"
 require_relative "client_search/related_configuration"
+require_relative "client_search/dropdown_configuration"
 require_relative "client_search/query_embedder_configuration"
 require_relative "client_search/configuration_accessors"
 require_relative "client_search/configuration"
@@ -22,4 +23,5 @@ require_relative "client_search/index_cache"
 require_relative "client_search/ollama_embedding_adapter"
 require_relative "client_search/generator"
 require_relative "client_search/related_tag"
+require_relative "client_search/dropdown_tag"
 require_relative "client_search/search_tag"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-client-search
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Svend Gundestrup
@@ -46,6 +46,7 @@ files:
 - assets/adapters/minisearch.js
 - assets/adapters/semantic.js
 - assets/client-search-base.js
+- assets/client-search-dropdown.js
 - assets/client-search-related.js
 - assets/includes/related-articles.html
 - assets/layouts/post-with-related.html
@@ -59,6 +60,8 @@ files:
 - lib/jekyll/client_search/configuration.rb
 - lib/jekyll/client_search/configuration_accessors.rb
 - lib/jekyll/client_search/document_builder.rb
+- lib/jekyll/client_search/dropdown_configuration.rb
+- lib/jekyll/client_search/dropdown_tag.rb
 - lib/jekyll/client_search/embedder_config_page.rb
 - lib/jekyll/client_search/embedding_configuration.rb
 - lib/jekyll/client_search/generator.rb