jekyll-client-search 0.1.0

data/docs/assets/icon.svg

@@ -0,0 +1,133 @@
+<svg width="900" height="950" viewBox="0 0 900 950" xmlns="http://www.w3.org/2000/svg">
+
+  <defs>
+    <style>
+      .dark { fill:#101826; }
+      .accent { fill:#e45842; }
+      .title {
+        font-family: Inter, Arial, Helvetica, sans-serif;
+        font-size: 88px;
+        font-weight: 700;
+      }
+      .subtitle {
+        font-family: Inter, Arial, Helvetica, sans-serif;
+        font-size: 32px;
+        fill: #6b7280;
+        letter-spacing: 3px;
+      }
+    </style>
+  </defs>
+
+  <!-- Main frame -->
+  <rect x="180"
+        y="40"
+        width="540"
+        height="540"
+        rx="45"
+        fill="white"
+        stroke="#101826"
+        stroke-width="16"/>
+
+  <!-- document -->
+
+  <rect x="280"
+        y="130"
+        width="250"
+        height="320"
+        rx="18"
+        fill="#101826"/>
+
+  <!-- folded corner -->
+  <polygon points="470,130 530,130 530,190"
+           class="accent"/>
+
+  <!-- text lines -->
+  <rect x="320" y="200" width="170" height="12" fill="white" opacity="0.9"/>
+  <rect x="320" y="245" width="140" height="12" fill="white" opacity="0.9"/>
+  <rect x="320" y="290" width="160" height="12" fill="white" opacity="0.9"/>
+  <rect x="320" y="335" width="120" height="12" fill="white" opacity="0.9"/>
+
+  <!-- accent highlight -->
+  <rect x="280"
+        y="395"
+        width="250"
+        height="55"
+        class="accent"/>
+
+  <!-- search badge -->
+  <g transform="translate(620,460)">
+
+      <circle r="120"
+              fill="#101826"
+              stroke="white"
+              stroke-width="8"/>
+
+      <!-- magnifier -->
+      <circle cx="-18"
+              cy="-18"
+              r="42"
+              fill="none"
+              stroke="white"
+              stroke-width="16"/>
+
+      <line x1="15"
+            y1="15"
+            x2="55"
+            y2="55"
+            stroke="white"
+            stroke-width="16"
+            stroke-linecap="round"/>
+
+      <!-- small accent dot -->
+      <circle cx="-70"
+              cy="-75"
+              r="10"
+              class="accent"/>
+
+  </g>
+
+  <!-- title -->
+
+  <text x="450"
+        y="720"
+        text-anchor="middle"
+        class="title">
+
+      <tspan fill="#101826">jekyll-client-</tspan>
+      <tspan fill="#e45842">search</tspan>
+
+  </text>
+
+  <!-- subtitle -->
+
+  <text x="450"
+        y="805"
+        text-anchor="middle"
+        class="subtitle">
+
+      FAST CLIENT-SIDE SEARCH FOR JEKYLL
+
+  </text>
+
+  <!-- decorative divider -->
+
+  <line x1="330"
+        y1="860"
+        x2="420"
+        y2="860"
+        stroke="#101826"
+        stroke-width="4"/>
+
+  <circle cx="450"
+          cy="860"
+          r="8"
+          class="accent"/>
+
+  <line x1="480"
+        y1="860"
+        x2="570"
+        y2="860"
+        stroke="#101826"
+        stroke-width="4"/>
+
+</svg>

data/lib/jekyll/client_search/configuration.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module ClientSearch
+    # Reads the +client_search+ section of the Jekyll site config and exposes
+    # validated, normalized values to the generator.
+    class Configuration
+      include ConfigurationAccessors
+      include EmbeddingConfiguration
+
+      ENGINES = %w[minisearch elasticlunr semantic].freeze
+
+      ENGINE_CDN_URLS = {
+        "minisearch" => "https://cdn.jsdelivr.net/npm/minisearch@7.2.0/dist/umd/index.min.js",
+        "elasticlunr" => "https://cdn.jsdelivr.net/npm/elasticlunr@0.9.5/elasticlunr.min.js",
+        "semantic" => nil
+      }.freeze
+
+      DEFAULTS = {
+        "enabled" => true,
+        "engine" => "minisearch",
+        "output" => "search-index.json",
+        "collections" => ["posts"],
+        "include_pages" => false,
+        "copy_runtime" => true,
+        "embedding" => {
+          "enabled" => false,
+          "model" => "embeddinggemma:300m",
+          "base_url" => "http://localhost:11434",
+          "connect_timeout" => 5,
+          "read_timeout" => 120,
+          "fail_on_error" => true,
+          "query_embedder" => {
+            "type" => "transformers"
+          }
+        }
+      }.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
+
+        @values = DEFAULTS.merge(configured)
+        @live_search = LiveSearchConfiguration.new(configured["live_search"] || {}, engine: engine)
+        @related = RelatedConfiguration.new(configured["related"] || {})
+        merge_embedding_config(configured["embedding"])
+        validate_engine!
+        return unless embedding_enabled?
+
+        validate_embedding!
+        validate_query_embedder!
+      end
+
+      private
+
+      def merge_embedding_config(configured_embedding)
+        embedding = configured_embedding || {}
+        unless embedding.is_a?(Hash)
+          raise Jekyll::Errors::FatalException,
+                "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,
+          build_base_url: embedding_base_url,
+          query_prefix: embedding_query_prefix
+        )
+      end
+
+      public
+
+      def enabled?
+        @values["enabled"] != false
+      end
+
+      def engine
+        @values.fetch("engine").to_s
+      end
+
+      def engine_url
+        @values.key?("engine_url") ? @values.fetch("engine_url") : ENGINE_CDN_URLS.fetch(engine)
+      end
+
+      def engine_sri
+        @values.fetch("engine_sri", nil)
+      end
+
+      def engine_crossorigin
+        @values.fetch("engine_crossorigin", nil)
+      end
+
+      def runtime_assets
+        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
+      end
+
+      def output
+        normalize_output(@values.fetch("output"))
+      end
+
+      def collections
+        Array(@values["collections"])
+          .compact
+          .map(&:to_s)
+          .reject(&:empty?)
+          .uniq
+      end
+
+      def include_pages?
+        @values["include_pages"] == true
+      end
+
+      def copy_runtime?
+        @values["copy_runtime"] != false
+      end
+
+      private
+
+      def validate_query_embedder!
+        query_embedder_model if engine == "semantic" && query_embedder_type == "transformers"
+      end
+
+      def validate_engine!
+        return if ENGINES.include?(engine)
+
+        raise Jekyll::Errors::FatalException,
+              "client_search engine must be one of #{ENGINES.join(', ')} (got #{engine.inspect})"
+      end
+
+      def normalize_output(value)
+        output = value.to_s.sub(%r{\A/+}, "")
+        normalized = Pathname.new(output).cleanpath.to_s
+        return normalized unless output.empty? || normalized == "." || normalized.start_with?("../")
+
+        raise Jekyll::Errors::FatalException,
+              "client_search output must be a relative file path inside the destination"
+      end
+    end
+  end
+end

data/lib/jekyll/client_search/configuration_accessors.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module ClientSearch
+    # Exposes auxiliary generated-runtime settings through Configuration.
+    module ConfigurationAccessors
+      def live_search_config
+        @live_search.to_h(engine: engine)
+      end
+
+      def related_enabled?
+        @related.enabled?
+      end
+
+      def related_output
+        @related.output
+      end
+
+      def related_configuration
+        @related
+      end
+
+      def query_embedder_type
+        @query_embedder.type
+      end
+
+      def query_embedder_model
+        @query_embedder.model
+      end
+
+      def query_embedder_api_url
+        @query_embedder.api_url
+      end
+
+      def query_embedder_asset
+        @query_embedder.asset
+      end
+
+      def query_embedder_assets
+        @query_embedder.assets
+      end
+
+      def query_embedder_config_json
+        @query_embedder.to_json
+      end
+    end
+  end
+end

data/lib/jekyll/client_search/document_builder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module ClientSearch
+    # Normalizes Jekyll documents and pages into the flat hash shape that the
+    # search index JSON emits.
+    class DocumentBuilder
+      def from_document(document)
+        url = document.url.to_s
+        return if url.empty?
+
+        data = document.data
+        {
+          "id" => url,
+          "title" => clean(data["title"] || "Untitled"),
+          "url" => url,
+          "excerpt" => clean(data["excerpt"] || excerpt_for(document)),
+          "content" => clean(document.content),
+          "categories" => normalize_list(data["categories"]),
+          "tags" => normalize_list(data["tags"]),
+          "date" => normalized_date(document),
+          "date_timestamp" => normalized_timestamp(document)
+        }.compact
+      end
+
+      private
+
+      def excerpt_for(document)
+        document.excerpt if document.respond_to?(:excerpt)
+      end
+
+      def normalize_list(value)
+        Array(value).compact.map { |item| clean(item) }.reject(&:empty?).uniq
+      end
+
+      def normalized_date(document)
+        value = document.data["date"] || document.date if document.respond_to?(:date)
+        return if value.nil? || value.to_s.empty?
+
+        value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+      end
+
+      def normalized_timestamp(document)
+        date = normalized_date(document)
+        date ? Time.iso8601(date).to_i : nil
+      rescue ArgumentError
+        nil
+      end
+
+      def clean(value)
+        cleaned = value.to_s
+                       .gsub(%r{<script\b[^>]*>.*?</script>}mi, " ")
+                       .gsub(%r{<style\b[^>]*>.*?</style>}mi, " ")
+                       .gsub(/\{%.*?%\}/m, " ")
+                       .gsub(/\{\{.*?\}\}/m, " ")
+                       .gsub(/!\[[^\]]*\]\([^)]*\)/, " ")
+                       .gsub(/<[^>]+>/, " ")
+                       .gsub(/[`*_>#\[\]()]/, " ")
+                       .gsub(/\s+/, " ")
+                       .gsub(/\s+([,.!?;:])/, '\\1')
+                       .strip
+        CGI.unescapeHTML(cleaned)
+      end
+    end
+  end
+end

data/lib/jekyll/client_search/embedder_config_page.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module ClientSearch
+    # Generates the browser query-embedder configuration JavaScript.
+    class EmbedderConfigPage < Jekyll::PageWithoutAFile
+      def initialize(site, configuration)
+        super(site, site.source, "assets", "search-embedder-config.js")
+        self.data = { "layout" => nil, "sitemap" => false }
+        self.content = "window.ClientSearchEmbedderConfig = #{configuration.query_embedder_config_json};\n"
+      end
+    end
+  end
+end

data/lib/jekyll/client_search/embedding_configuration.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module ClientSearch
+    # Provides build-time embedding settings and model-specific prefixes.
+    module EmbeddingConfiguration
+      PREFIXES = {
+        "embeddinggemma" => {
+          "document" => "title: none | text: ",
+          "query" => "task: search result | query: "
+        },
+        "nomic-embed-text" => {
+          "document" => "search_document: ",
+          "query" => "search_query: "
+        }
+      }.freeze
+
+      def embedding_enabled?
+        @values.fetch("embedding").fetch("enabled") == true
+      end
+
+      def embedding_model
+        @values.fetch("embedding").fetch("model").to_s
+      end
+
+      def embedding_base_url
+        @values.fetch("embedding").fetch("base_url").to_s
+      end
+
+      def embedding_connect_timeout
+        positive_timeout("connect_timeout")
+      end
+
+      def embedding_read_timeout
+        positive_timeout("read_timeout")
+      end
+
+      def embedding_fail_on_error?
+        @values.fetch("embedding").fetch("fail_on_error") != false
+      end
+
+      def embedding_include_in_index?
+        configured = @values.fetch("embedding")["include_in_index"]
+        configured.nil? ? engine == "semantic" : configured == true
+      end
+
+      def embedding_document_prefix
+        configured_prefix("document_prefix", "document")
+      end
+
+      def embedding_query_prefix
+        configured_prefix("query_prefix", "query")
+      end
+
+      def embedding_identity
+        {
+          "provider" => "ollama",
+          "model" => embedding_model,
+          "base_url" => embedding_base_url,
+          "document_prefix" => embedding_document_prefix,
+          "query_prefix" => embedding_query_prefix,
+          "schema" => 2
+        }
+      end
+
+      private
+
+      def configured_prefix(config_key, role)
+        embedding = @values.fetch("embedding")
+        return embedding.fetch(config_key).to_s if embedding.key?(config_key)
+
+        model_name = embedding_model.split(":").first
+        PREFIXES.fetch(model_name, {}).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
+
+        value
+      end
+
+      def validate_embedding!
+        raise Jekyll::Errors::FatalException, "embedding model must not be empty" if embedding_model.empty?
+        raise Jekyll::Errors::FatalException, "embedding base_url must not be empty" if embedding_base_url.empty?
+
+        embedding_connect_timeout
+        embedding_read_timeout
+      end
+    end
+  end
+end

data/lib/jekyll/client_search/generator.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module ClientSearch
+    # Jekyll generator that emits the search index JSON and copies browser
+    # runtime assets (base + selected engine adapter) for client-side
+    # JavaScript search engines. Optionally enhances documents with
+    # embeddings from a local Ollama server, using a content-hash cache to
+    # avoid re-embedding unchanged documents.
+    class Generator < Jekyll::Generator
+      safe true
+      priority :low
+
+      def generate(site)
+        configuration = Configuration.new(site)
+        return unless configuration.enabled?
+
+        documents = build_documents(site, configuration)
+        documents = enhance_with_embeddings(site, documents, configuration) if configuration.embedding_enabled?
+        add_generated_pages(site, documents, configuration)
+        add_runtime_asset(site, configuration) if configuration.copy_runtime?
+      end
+
+      private
+
+      def add_generated_pages(site, documents, configuration)
+        add_related_page(site, documents, configuration) if configuration.related_enabled?
+        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?
+        add_embedder_config(site, configuration) if semantic_query_embedder?(configuration)
+      end
+
+      def build_documents(site, configuration)
+        builder = DocumentBuilder.new
+        documents = collection_documents(site, configuration, builder)
+        documents.concat(page_documents(site, builder, configuration)) if configuration.include_pages?
+        documents.compact.uniq { |document| document["id"] }
+      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
+        documents
+      end
+
+      def build_embedding_adapter(configuration)
+        OllamaEmbeddingAdapter.new(
+          model: configuration.embedding_model,
+          base_url: configuration.embedding_base_url,
+          connect_timeout: configuration.embedding_connect_timeout,
+          read_timeout: configuration.embedding_read_timeout
+        )
+      end
+
+      def add_related_page(site, documents, configuration)
+        relation_data = RelatedAnalyzer.new(configuration.related_configuration).analyze(documents)
+        site.pages << RelatedPage.new(site, configuration.related_output, relation_data)
+      end
+
+      def remove_embeddings(documents)
+        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
+
+        embedding = adapter.embed(embedding_text(document, configuration))
+        if embedding
+          document["embedding"] = embedding
+          cache.store(document["id"], hash, embedding)
+        elsif configuration.embedding_fail_on_error?
+          raise Jekyll::Errors::FatalException,
+                "embedding generation failed for document #{document['id'].inspect}"
+        end
+      end
+
+      def embedding_text(document, configuration)
+        text = [document["title"], document["excerpt"], document["content"]].compact.join(" ")
+        "#{configuration.embedding_document_prefix}#{text}"
+      end
+
+      def collection_documents(site, configuration, builder)
+        configuration.collections.flat_map do |label|
+          collection = label == "posts" ? site.posts : site.collections[label]
+          next [] unless collection
+
+          collection.docs.filter_map { |document| builder.from_document(document) }
+        end
+      end
+
+      def page_documents(site, builder, configuration)
+        site.pages
+            .reject { |page| page.url == "/#{configuration.output}" }
+            .select { |page| page.data["title"] }
+            .filter_map { |page| builder.from_document(page) }
+      end
+
+      def add_runtime_asset(site, configuration)
+        root = File.expand_path("../../..", __dir__)
+        configuration.runtime_assets.each do |asset|
+          relative = asset.sub(%r{\A/}, "")
+          next if site.static_files.any? { |file| normalized_path(file.relative_path) == relative }
+
+          base = File.dirname(asset)
+          name = File.basename(asset)
+          site.static_files << Jekyll::StaticFile.new(site, root, base, name)
+        end
+      end
+
+      def add_embedder_config(site, configuration)
+        site.pages << EmbedderConfigPage.new(site, configuration)
+      end
+
+      def semantic_query_embedder?(configuration)
+        configuration.engine == "semantic" && configuration.embedding_enabled? &&
+          configuration.query_embedder_type != "none"
+      end
+
+      def normalized_path(path)
+        path.to_s.sub(%r{\A/}, "")
+      end
+    end
+  end
+end