jekyll-client-search 0.1.0

data/assets/client-search-related.js

@@ -0,0 +1,176 @@
+(function () {
+    "use strict";
+
+    function safeUrl(value) {
+        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 formatDate(timestamp) {
+        if (!timestamp) {
+            return "";
+        }
+        try {
+            return new Date(timestamp * 1000).toLocaleDateString(undefined, {
+                year: "numeric", month: "short", day: "numeric"
+            });
+        } catch (_error) {
+            return "";
+        }
+    }
+
+    function appendMeta(parent, className, text) {
+        if (!text) {
+            return;
+        }
+        var span = document.createElement("span");
+        span.className = className;
+        span.textContent = text;
+        parent.appendChild(span);
+    }
+
+    function defaultRenderItem(item) {
+        var entry = document.createElement("li");
+        entry.className = "related-article-item";
+
+        var link = document.createElement("a");
+        link.href = safeUrl(item.url);
+        link.textContent = item.title || item.url;
+        link.className = "related-article-link";
+        entry.appendChild(link);
+
+        var metaParts = [];
+        if (item.date_timestamp) {
+            var dateSpan = document.createElement("span");
+            dateSpan.className = "related-article-date";
+            dateSpan.textContent = formatDate(item.date_timestamp);
+            metaParts.push(dateSpan);
+        }
+        if (Array.isArray(item.shared_tags) && item.shared_tags.length) {
+            appendMeta(entry, "related-article-tags", item.shared_tags.join(", "));
+        }
+        if (Array.isArray(item.shared_categories) && item.shared_categories.length) {
+            appendMeta(entry, "related-article-categories", item.shared_categories.join(", "));
+        }
+        if (metaParts.length) {
+            var meta = document.createElement("div");
+            meta.className = "related-article-meta";
+            metaParts.forEach(function (el) { meta.appendChild(el); });
+            entry.appendChild(meta);
+        }
+
+        if (item.excerpt) {
+            var excerpt = document.createElement("p");
+            excerpt.className = "related-article-excerpt";
+            excerpt.textContent = item.excerpt;
+            entry.appendChild(excerpt);
+        }
+
+        return entry;
+    }
+
+    function sortItems(items, sortOrder) {
+        if (sortOrder === "date") {
+            items.sort(function (a, b) {
+                return (b.date_timestamp || 0) - (a.date_timestamp || 0) ||
+                    String(a.title).localeCompare(String(b.title));
+            });
+        } else {
+            items.sort(function (a, b) {
+                return (b.score || 0) - (a.score || 0) ||
+                    String(a.title).localeCompare(String(b.title));
+            });
+        }
+    }
+
+    function render(container, relations, sortOrder, options) {
+        var items = relations.slice();
+        if (typeof options.filter === "function") {
+            items = items.filter(function (item, index, array) {
+                return options.filter(item, index, array);
+            });
+        }
+        sortItems(items, sortOrder);
+
+        container.replaceChildren();
+        if (items.length === 0) {
+            return;
+        }
+
+        var heading = document.createElement("h2");
+        heading.textContent = "Related articles";
+        var list = document.createElement("ul");
+        list.className = "related-articles-list";
+
+        var renderItem = options.renderItem || defaultRenderItem;
+        items.forEach(function (item) {
+            var entry = renderItem(item, document);
+            if (entry) {
+                list.appendChild(entry);
+            }
+        });
+        container.append(heading, list);
+    }
+
+    function resolveSort(container, sortControl, fallback) {
+        if (sortControl) {
+            return sortControl.value || fallback;
+        }
+        if (container.dataset.relatedSort) {
+            return container.dataset.relatedSort;
+        }
+        return fallback;
+    }
+
+    window.ClientSearchRelated = {
+        run: function (options) {
+            options = Object.assign({
+                container: "#related-articles",
+                sortControl: "#related-sort",
+                relationsUrl: window.clientSearchConfig && window.clientSearchConfig.relatedUrl,
+                currentUrl: window.location.pathname,
+                sort: (window.clientSearchConfig && window.clientSearchConfig.relatedSort) || "relevance",
+                renderItem: null,
+                filter: null
+            }, options || {});
+            var container = document.querySelector(options.container);
+            if (!container || !options.relationsUrl) {
+                return Promise.resolve();
+            }
+
+            return fetch(options.relationsUrl, { headers: { Accept: "application/json" } })
+                .then(function (response) {
+                    if (!response.ok) {
+                        throw new Error("Unable to load related articles");
+                    }
+                    return response.json();
+                })
+                .then(function (data) {
+                    var relations = (data.relations && data.relations[options.currentUrl]) || [];
+                    var sortControl = document.querySelector(options.sortControl);
+                    var sort = resolveSort(container, sortControl, options.sort);
+                    render(container, relations, sort, options);
+                    if (sortControl) {
+                        sortControl.addEventListener("change", function () {
+                            render(container, relations, sortControl.value, options);
+                        });
+                    }
+                })
+                .catch(function () {
+                    container.replaceChildren();
+                });
+        }
+    };
+
+    if (document.querySelector("#related-articles")) {
+        window.ClientSearchRelated.run();
+    }
+}());

data/assets/includes/related-articles.html

@@ -0,0 +1,36 @@
+---
+# Reference include for related articles.
+#
+# Copy this file into your site's _includes/ directory:
+#   cp $(bundle show jekyll-client-search)/assets/includes/related-articles.html _includes/
+#
+# Then add one line to your post layout:
+#   {% include related-articles.html %}
+#
+# Or use the Liquid tag directly (no file copy needed):
+#   {% related_articles %}
+#
+# Available parameters via include variables:
+#   sort: "relevance" (default) or "date"
+#   scripts: true (default) to load runtime scripts, false to skip
+---
+
+{% assign related_sort = include.sort | default: "relevance" %}
+{% assign include_scripts = include.scripts | default: true %}
+{% if include_scripts == false or include_scripts == "false" %}
+  {% assign include_scripts = false %}
+{% endif %}
+
+<section class="related-articles-section">
+  <label for="related-sort">Sort related articles</label>
+  <select id="related-sort">
+    <option value="relevance">Most related</option>
+    <option value="date">Newest</option>
+  </select>
+  <div id="related-articles" data-related-sort="{{ related_sort }}"></div>
+</section>
+
+{% if include_scripts %}
+<script src="{{ '/assets/search-runtime-config.js' | relative_url }}"></script>
+<script src="{{ '/assets/client-search-related.js' | relative_url }}"></script>
+{% endif %}

data/assets/layouts/post-with-related.html

@@ -0,0 +1,54 @@
+---
+# Reference post layout with related articles.
+#
+# Copy this file into your site's _layouts/ directory and adapt it:
+#   cp $(bundle show jekyll-client-search)/assets/layouts/post-with-related.html _layouts/
+#
+# Then use it in front matter:
+#   layout: post-with-related
+#
+# This is a minimal starting point. Most sites already have a post layout
+# they like — in that case, just add the {% related_articles %} tag or
+# {% include related-articles.html %} to your existing layout instead.
+---
+<!doctype html>
+<html lang="{{ page.lang | default: site.lang | default: 'en' }}">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{ page.title | default: site.title }}</title>
+</head>
+<body>
+  <header>
+    <a href="{{ '/' | relative_url }}">{{ site.title }}</a>
+  </header>
+
+  <main>
+    <article>
+      <h1>{{ page.title }}</h1>
+      {% if page.date %}
+      <p class="post-date">
+        Published: {{ page.date | date: '%b %-d, %Y' }}
+        {% if page.author %} by {{ page.author }}{% endif %}
+      </p>
+      {% endif %}
+
+      {{ content }}
+
+      {% if page.tags and page.tags.size > 0 %}
+      <div class="tags">
+        {% for tag in page.tags %}
+          <span class="tag">{{ tag }}</span>
+        {% endfor %}
+      </div>
+      {% endif %}
+    </article>
+
+    {% related_articles %}
+  </main>
+
+  <footer>
+    <p>&copy; {{ site.time | date: '%Y' }} {{ site.title }}</p>
+  </footer>
+</body>
+</html>

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

@@ -0,0 +1,63 @@
+(function () {
+    "use strict";
+
+    var config = window.ClientSearchEmbedderConfig || {};
+    var model = config.model || config.buildModel || "embeddinggemma:300m";
+    var apiUrl = config.apiUrl || "http://localhost:11434/api/embed";
+    var activeController = null;
+
+    function reportStatus(message) {
+        window.dispatchEvent(new CustomEvent("client-search:status", {
+            detail: { message: message }
+        }));
+    }
+
+    window.ClientSearchQueryEmbedder = async function (query) {
+        if (activeController) {
+            activeController.abort();
+        }
+        var controller = new AbortController();
+        var timeoutMs = Number.isInteger(config.timeoutMs) ? config.timeoutMs : 30000;
+        var timedOut = false;
+        var timer = setTimeout(function () {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        activeController = controller;
+        reportStatus("Contacting semantic search…");
+
+        try {
+            var response = await fetch(apiUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    model: model,
+                    input: (config.queryPrefix || "") + query
+                }),
+                signal: controller.signal
+            });
+
+            if (!response.ok) {
+                throw new Error("Ollama API returned " + response.status);
+            }
+
+            var data = await response.json();
+            var embedding = data.embeddings && data.embeddings[0];
+            if (!embedding || embedding.length === 0) {
+                throw new Error("Ollama API returned empty embedding");
+            }
+
+            return embedding;
+        } catch (error) {
+            if (timedOut) {
+                throw new Error("Ollama API request timed out");
+            }
+            throw error;
+        } finally {
+            clearTimeout(timer);
+            if (activeController === controller) {
+                activeController = null;
+            }
+        }
+    };
+}());

data/assets/query-embedders/transformers-worker.js

@@ -0,0 +1,130 @@
+"use strict";
+
+var runtimePromise = null;
+var modelPromise = null;
+var activeConfig = null;
+var inferenceQueue = Promise.resolve();
+var latestRequestId = null;
+
+function reportStatus(message) {
+    self.postMessage({ type: "status", message: message });
+}
+
+function configureRuntime(runtime) {
+    if (activeConfig.modelBaseUrl && runtime.env) {
+        runtime.env.localModelPath = activeConfig.modelBaseUrl;
+        runtime.env.allowRemoteModels = false;
+    }
+    if (activeConfig.wasmBaseUrl && runtime.env && runtime.env.backends &&
+        runtime.env.backends.onnx && runtime.env.backends.onnx.wasm) {
+        runtime.env.backends.onnx.wasm.wasmPaths = activeConfig.wasmBaseUrl;
+    }
+    return runtime;
+}
+
+function retry(operation) {
+    var attempts = Number.isInteger(activeConfig.retryAttempts) ? activeConfig.retryAttempts : 1;
+    return operation().catch(function retryAfterFailure(error) {
+        if (attempts <= 0) {
+            throw error;
+        }
+        attempts -= 1;
+        return new Promise(function (resolve) {
+            setTimeout(resolve, 1000);
+        }).then(operation).catch(retryAfterFailure);
+    });
+}
+
+function progress(update) {
+    if (update && Number.isFinite(update.progress)) {
+        reportStatus("Loading semantic model… " + Math.round(update.progress) + "%");
+    } else {
+        reportStatus("Loading semantic model…");
+    }
+}
+
+function loadRuntime() {
+    if (self.ClientSearchTransformers) {
+        return Promise.resolve(configureRuntime(self.ClientSearchTransformers));
+    }
+    if (!runtimePromise) {
+        runtimePromise = retry(function () {
+            return import(
+                activeConfig.libraryUrl ||
+                "https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.8.1"
+            ).then(configureRuntime);
+        }).catch(function (error) {
+            runtimePromise = null;
+            throw error;
+        });
+    }
+    return runtimePromise;
+}
+
+function loadModel() {
+    if (!modelPromise) {
+        reportStatus("Loading semantic model…");
+        modelPromise = retry(function () {
+            return loadRuntime().then(async function (runtime) {
+                var modelId = activeConfig.model || "onnx-community/embeddinggemma-300m-ONNX";
+                var tokenizer = await runtime.AutoTokenizer.from_pretrained(modelId, {
+                    progress_callback: progress
+                });
+                var options = {
+                    dtype: activeConfig.dtype || "q8",
+                    progress_callback: progress
+                };
+                if (activeConfig.device) {
+                    options.device = activeConfig.device;
+                }
+                var model = await runtime.AutoModel.from_pretrained(modelId, options);
+                return { tokenizer: tokenizer, model: model };
+            });
+        }).catch(function (error) {
+            modelPromise = null;
+            throw error;
+        });
+    }
+    return modelPromise;
+}
+
+async function embed(query) {
+    var loaded = await loadModel();
+    reportStatus("Embedding query…");
+    var input = (activeConfig.queryPrefix || "") + query;
+    var tokens = await loaded.tokenizer([input], {
+        padding: true,
+        truncation: true,
+        max_length: Number.isInteger(activeConfig.maxTokens) ? activeConfig.maxTokens : 512
+    });
+    var output = await loaded.model(tokens);
+    var embedding = output.sentence_embedding;
+    if (!embedding || !embedding.data) {
+        throw new Error("Transformers model returned no sentence embedding");
+    }
+    return Array.from(embedding.data);
+}
+
+self.addEventListener("message", function (event) {
+    var message = event.data || {};
+    activeConfig = activeConfig || message.config || {};
+    latestRequestId = message.id;
+    inferenceQueue = inferenceQueue.then(function () {
+        if (message.id !== latestRequestId) {
+            return null;
+        }
+        return embed(message.query);
+    }).then(function (embedding) {
+        if (embedding && message.id === latestRequestId) {
+            self.postMessage({ type: "result", id: message.id, embedding: embedding });
+        }
+    }, function (error) {
+        if (message.id === latestRequestId) {
+            self.postMessage({
+                type: "error",
+                id: message.id,
+                error: error && error.message ? error.message : String(error)
+            });
+        }
+    });
+});

data/assets/query-embedders/transformers.js

@@ -0,0 +1,223 @@
+(function () {
+    "use strict";
+
+    var config = window.ClientSearchEmbedderConfig || {};
+    var modelId = config.model || "onnx-community/embeddinggemma-300m-ONNX";
+    var runtimePromise = null;
+    var modelPromise = null;
+    var worker = null;
+    var workerUnavailable = false;
+    var workerRequests = new Map();
+    var nextWorkerRequestId = 1;
+    var currentScriptUrl = document.currentScript && document.currentScript.src;
+
+    function reportStatus(message) {
+        window.dispatchEvent(new CustomEvent("client-search:status", {
+            detail: { message: message }
+        }));
+    }
+
+    function configureRuntime(runtime) {
+        if (config.modelBaseUrl && runtime.env) {
+            runtime.env.localModelPath = config.modelBaseUrl;
+            runtime.env.allowRemoteModels = false;
+        }
+        if (config.wasmBaseUrl && runtime.env && runtime.env.backends &&
+            runtime.env.backends.onnx && runtime.env.backends.onnx.wasm) {
+            runtime.env.backends.onnx.wasm.wasmPaths = config.wasmBaseUrl;
+        }
+        return runtime;
+    }
+
+    function retry(operation) {
+        var attempts = Number.isInteger(config.retryAttempts) ? config.retryAttempts : 1;
+        return operation().catch(function retryAfterFailure(error) {
+            if (attempts <= 0) {
+                throw error;
+            }
+            attempts -= 1;
+            return new Promise(function (resolve) {
+                setTimeout(resolve, 1000);
+            }).then(operation).catch(retryAfterFailure);
+        });
+    }
+
+    function withTimeout(promise) {
+        var timeoutMs = Number.isInteger(config.timeoutMs) ? config.timeoutMs : 300000;
+        return new Promise(function (resolve, reject) {
+            var timer = setTimeout(function () {
+                reject(new Error("Transformers model loading timed out"));
+            }, timeoutMs);
+            promise.then(function (value) {
+                clearTimeout(timer);
+                resolve(value);
+            }, function (error) {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    }
+
+    function progress(update) {
+        if (update && Number.isFinite(update.progress)) {
+            reportStatus("Loading semantic model… " + Math.round(update.progress) + "%");
+        } else {
+            reportStatus("Loading semantic model…");
+        }
+    }
+
+    function loadRuntime() {
+        if (window.ClientSearchTransformers) {
+            return Promise.resolve(configureRuntime(window.ClientSearchTransformers));
+        }
+        if (!runtimePromise) {
+            runtimePromise = retry(function () {
+                return import(
+                    config.libraryUrl ||
+                    "https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.8.1"
+                ).then(configureRuntime);
+            }).catch(function (error) {
+                runtimePromise = null;
+                throw error;
+            });
+        }
+        return runtimePromise;
+    }
+
+    function loadModel() {
+        if (!modelPromise) {
+            reportStatus("Loading semantic model…");
+            modelPromise = retry(function () {
+                return loadRuntime().then(async function (runtime) {
+                    var tokenizer = await runtime.AutoTokenizer.from_pretrained(modelId, {
+                        progress_callback: progress
+                    });
+                    var options = {
+                        dtype: config.dtype || "q8",
+                        progress_callback: progress
+                    };
+                    if (config.device) {
+                        options.device = config.device;
+                    }
+                    var model = await runtime.AutoModel.from_pretrained(modelId, options);
+                    return { tokenizer: tokenizer, model: model };
+                });
+            }).catch(function (error) {
+                modelPromise = null;
+                throw error;
+            });
+        }
+        return withTimeout(modelPromise);
+    }
+
+    async function embedInline(query) {
+        var loaded = await loadModel();
+        reportStatus("Embedding query…");
+        var input = (config.queryPrefix || "") + query;
+        var tokens = await loaded.tokenizer([input], {
+            padding: true,
+            truncation: true,
+            max_length: Number.isInteger(config.maxTokens) ? config.maxTokens : 512
+        });
+        var output = await loaded.model(tokens);
+        var embedding = output.sentence_embedding;
+        if (!embedding || !embedding.data) {
+            throw new Error("Transformers model returned no sentence embedding");
+        }
+        return Array.from(embedding.data);
+    }
+
+    function workerUrl() {
+        if (config.workerUrl) {
+            return config.workerUrl;
+        }
+        if (currentScriptUrl) {
+            return new URL("transformers-worker.js", currentScriptUrl).href;
+        }
+        return "/assets/query-embedders/transformers-worker.js";
+    }
+
+    function rejectWorkerRequests(error, useFallback) {
+        workerRequests.forEach(function (request) {
+            clearTimeout(request.timer);
+            if (useFallback) {
+                embedInline(request.query).then(request.resolve, request.reject);
+            } else {
+                request.reject(error);
+            }
+        });
+        workerRequests.clear();
+    }
+
+    function createWorker() {
+        if (worker || workerUnavailable || config.worker === false || typeof Worker !== "function") {
+            return worker;
+        }
+        try {
+            worker = new Worker(workerUrl(), { type: "module" });
+            worker.addEventListener("message", function (event) {
+                var message = event.data || {};
+                if (message.type === "status") {
+                    reportStatus(message.message);
+                    return;
+                }
+                var request = workerRequests.get(message.id);
+                if (!request) {
+                    return;
+                }
+                clearTimeout(request.timer);
+                workerRequests.delete(message.id);
+                if (message.type === "result") {
+                    request.resolve(message.embedding);
+                } else {
+                    request.reject(new Error(message.error || "Transformers worker failed"));
+                }
+            });
+            worker.addEventListener("error", function () {
+                workerUnavailable = true;
+                worker.terminate();
+                worker = null;
+                rejectWorkerRequests(new Error("Transformers worker failed"), true);
+            });
+        } catch (_error) {
+            workerUnavailable = true;
+            worker = null;
+        }
+        return worker;
+    }
+
+    function abortObsoleteWorkerRequests() {
+        workerRequests.forEach(function (request) {
+            clearTimeout(request.timer);
+            var error = new Error("Obsolete semantic query");
+            error.name = "AbortError";
+            request.reject(error);
+        });
+        workerRequests.clear();
+    }
+
+    function embedWithWorker(query) {
+        var activeWorker = createWorker();
+        if (!activeWorker) {
+            return embedInline(query);
+        }
+        abortObsoleteWorkerRequests();
+        return new Promise(function (resolve, reject) {
+            var id = nextWorkerRequestId++;
+            var timeoutMs = Number.isInteger(config.timeoutMs) ? config.timeoutMs : 300000;
+            var timer = setTimeout(function () {
+                workerRequests.delete(id);
+                reject(new Error("Transformers worker timed out"));
+            }, timeoutMs);
+            workerRequests.set(id, {
+                query: query,
+                resolve: resolve,
+                reject: reject,
+                timer: timer
+            });
+            activeWorker.postMessage({ id: id, query: query, config: config });
+        });
+    }
+
+    window.ClientSearchQueryEmbedder = embedWithWorker;
+}());