jekyll-client-search 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b07a5519cf45012ce0d198cedfe93e1e93e939ed9d9221386af87c10854f0cf4
-  data.tar.gz: 630a3dd0f345e4e263c8228ac3a565610b435723860dac1125e86bf780d072b1
+  metadata.gz: ed1c7a635cc419d9fb130411ced8e64a473c016e8188e36ddd98ea6922a098f7
+  data.tar.gz: f320844ded59274df991b1aa3d56fb22560e818105c5a0e682ea6e6a0c67df88
 SHA512:
-  metadata.gz: 0d53f70fa2e1f37facfebe56ebf3384f3d5c376672e08f93cc5a3a761b03a294843b0cf236cbda9ffa7a7ace87261683a525f3a5e12e9da61592946cc878024a
-  data.tar.gz: 458dc19c9c0ad2b6c017057694b1af2103d918f16584205ec7c144a5e696fcb0d5609508fa414a7cb91facccf39a75dcd0c1c3e8c8a8e67bac8d1a09665419b5
+  metadata.gz: a12fb0052f9a727baf957735cd23fc9759f46fe7b54977acd16ed63edb14b0d63e2594d3c2bee936c9317541f8810a654acf7a5369746c9d11c39699457cf351
+  data.tar.gz: 46986b4c1a0107821f6932d8538c1aff0fcc386ddb9e9f787a4890da5f8af3ccd30a8c0b6b9257d928d3b52aa6fe625806136812cfbf781763a0f3a391cf9aa6

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 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
+- Generic `passthrough_fields` config option: external plugins declare which document `data` fields to forward into the search index (e.g. `file_type`, `icon_url`, `icon_set` from jekyll-documents)
+- Field renaming in `passthrough_fields`: entries can be strings (same name) or hashes (`{source => target}`) for integration with other search conventions
+- `icon_field` config option (default: `"icon_url"`): tells the browser runtime which field to render as an `<img>` icon before the result title; set to `null` to disable
+- Search index now includes `source` (collection label: `posts`, `pages`, etc.) — always present, set by the generator
+- Result `<article>` elements carry `data-source`, `data-categories`, `data-tags`, plus `data-*` for all passthrough fields (snake_case → data-kebab-case) for CSS-based result customization
+
+### Fixed
+- Allow whitespace in script/style end tags in `DocumentBuilder#clean` (`</script\s*>` instead of `</script>`) — CodeQL: bad HTML filtering regexp
+- Fix polynomial ReDoS in `SearchTag` and `RelatedTag` syntax regexes — strip markup before matching, remove leading/trailing `\s*` patterns that caused O(n²) backtracking (CodeQL: polynomial regex on uncontrolled data)
+
+### Changed
+- Simplified release workflow to tag-push trigger (`push: tags: v*`) — no manual `gh release create` needed
+- Switched to RubyGems trusted publishing (`rubygems/release-gem@v1` with OIDC)
+- Centralized version in `version.rb` as single source of truth — removed `version` field from `package.json`
+- Added `rake version:bump` and `rake version:check_changelog` tasks
+- Added CHANGELOG gate to release workflow (fails if entry missing for the version)
+- Added `npm audit` and `npm outdated` (non-blocking) to CI
+- Replaced pre-commit hook with rubocop-only (fast); added pre-push hook (rubocop + rspec)
+- Dropped reek from quality stack (KISS — marginal value on a small gem)
+- Aligned AGENTS.md to the open convention; added CLAUDE.md and .windsurfrules pointer files
+
 ## 0.1.0 — 2026-08-25
 
 - Add a pluggable search engine architecture with a base runtime and adapters.

data/README.developer.md

@@ -12,14 +12,66 @@ 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
 committed baseline JSON artifacts. No network access or external services
 are required for the default test run.
 
+## Quality checks and git hooks
+
+The project uses a focused quality stack: RuboCop (style), bundler-audit
+(security), RSpec (Ruby tests), and `npm test` (JavaScript tests). This
+covers the actionable ground without the maintenance burden of additional
+code-smell tools on a small focused gem.
+
+### Rake tasks
+
+| Task | What it runs |
+| --- | --- |
+| `rake` (default) | `rake quality` — all checks below |
+| `rake quality` | rubocop + bundler-audit + rspec + npm test |
+| `rake quick` | rubocop + rspec (fast pre-push subset) |
+| `rake rubocop` | RuboCop style check |
+| `rake rubocop_fix` | RuboCop auto-fix |
+| `rake bundler_audit` | `bundle-audit check --update` security scan |
+| `rake spec` | RSpec test suite |
+| `rake npm_test` | JavaScript test suite (`npm test`) |
+| `rake ci` | rspec + rubocop + syntax checks + npm test + gem build |
+
+### Git hooks
+
+Git hooks are not committed to the repository. Install them locally after
+cloning:
+
+```bash
+bin/install-hooks.sh
+```
+
+This installs two hooks:
+
+| Hook | What it runs | When |
+| --- | --- | --- |
+| `pre-commit` | `rubocop` only (~2s) | Before each commit |
+| `pre-push` | `rubocop + rspec` (~15s) | Before each push |
+
+The pre-commit hook is intentionally fast (style only) to avoid bypassing
+with `--no-verify`. The full test suite runs on pre-push and in CI. Skip
+either with `git commit --no-verify` or `git push --no-verify`.
+
+### CI checks
+
+The [CI workflow](.github/workflows/ci.yml) runs on every push and pull
+request across Ruby 3.2/3.3/3.4 and Node 22/24:
+
+- `bundle exec rake ci` (rspec, rubocop, syntax checks, npm test, gem build)
+- `bundle exec bundle-audit check --update` (Ruby dependency security)
+- `npm audit --audit-level=high` (JavaScript dependency security)
+- `npm outdated` (non-blocking — warns about outdated npm packages)
+
 ## Build-time related articles
 
 The optional related-analysis pass writes `search-relations.json` separately
@@ -62,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
 
@@ -197,8 +244,223 @@ 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
 fixtures or Ollama. The committed baseline JSON and semantic embeddings
 ensure all tests pass in CI without external dependencies.
+
+## Releasing
+
+Releases are published to RubyGems.org via the
+[`release.yml`](.github/workflows/release.yml) GitHub Actions workflow,
+which triggers automatically when a GitHub Release is published. The
+workflow uses RubyGems trusted publishing (OIDC) — no API key is stored
+in the repository.
+
+### Prerequisites (one-time setup)
+
+Trusted publishing must be configured on rubygems.org for the gem before
+the first release:
+
+1. Log into <https://rubygems.org> and open the gem's page.
+2. Go to **Settings → Trusted Publishers → Add trusted publisher**.
+3. Enter:
+   - **Repository**: `gundestrup/jekyll-client-search`
+   - **Workflow filename**: `release.yml`
+   - **Environment**: `release`
+
+If the gem has never been published before, rubygems.org may require a
+one-time manual `gem push` with an API key to create the gem name before
+a trusted publisher can be attached. After that, all subsequent releases
+use trusted publishing automatically.
+
+### Version bumping
+
+The version lives in [`lib/jekyll/client_search/version.rb`](lib/jekyll/client_search/version.rb)
+and follows [Semantic Versioning](https://semver.org/). The gemspec reads
+from this file — it is the **single source of truth**. No other file
+stores the version (`package.json` is `private: true` and has no version
+field). Use the rake task to bump it:
+
+```bash
+bundle exec rake "version:bump[patch]"   # 0.1.0 -> 0.1.1  (bug fixes)
+bundle exec rake "version:bump[minor]"   # 0.1.0 -> 0.2.0  (new features, backwards compatible)
+bundle exec rake "version:bump[major]"   # 0.1.0 -> 1.0.0  (incompatible API changes)
+```
+
+The rake task only edits `version.rb`. It does not commit, tag, or update
+the changelog — those are manual steps in the release checklist below.
+
+You can verify that the CHANGELOG has an entry for the current version:
+
+```bash
+bundle exec rake version:check_changelog
+```
+
+This check also runs in the release workflow — the publish will fail if
+`CHANGELOG.md` has no `## X.Y.Z` entry matching the version being released.
+
+### Release checklist
+
+1. **Ensure the working tree is clean** and on `main`:
+
+   ```bash
+   git status
+   ```
+
+2. **Ensure all 80 fixture posts are present** (needed for Ollama
+   integration tests and baseline regeneration):
+
+   ```bash
+   ruby spec/fixtures/download_arxiv.rb
+   ```
+
+   Requires `pdftotext` (`brew install poppler` on macOS). Skip if the
+   arXiv posts are already present and unchanged.
+
+3. **Run the full test suite locally**, including Ollama integration tests:
+
+   ```bash
+   bundle exec rspec
+   OLLAMA_INTEGRATION=1 bundle exec rspec spec/ollama_integration_spec.rb
+   OLLAMA_INTEGRATION=1 bundle exec rspec spec/llm_injection_spec.rb
+   bundle exec rubocop
+   npm test
+   npm run lint
+   gem build jekyll-client-search.gemspec
+   ```
+
+   The Ollama integration tests require a running [Ollama](https://ollama.ai/)
+   server with the `embeddinggemma:300m` model pulled (`ollama pull
+   embeddinggemma:300m`). Do not publish a release until the Ollama
+   integration tests pass locally — they are skipped by default and will
+   not block CI, so they must be run manually before each release.
+
+4. **Bump the version** (see above) and update the `## Unreleased` or new
+   `## X.Y.Z — YYYY-MM-DD` section at the top of
+   [`CHANGELOG.md`](CHANGELOG.md) with a user-facing summary of changes.
+
+5. **Commit the version bump and changelog**:
+
+   ```bash
+   git add lib/jekyll/client_search/version.rb CHANGELOG.md
+   git commit -m "Release X.Y.Z: <short summary>"
+   ```
+
+6. **Tag the release** with an annotated tag:
+
+   ```bash
+   git tag -a vX.Y.Z -m "Release X.Y.Z
+
+   <one-line summary of notable changes>"
+   ```
+
+7. **Push `main` and the tag** to GitHub — pushing the tag triggers the
+   release workflow automatically:
+
+   ```bash
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+
+   No manual `gh release create` is needed. The workflow builds the gem,
+   attaches it to a GitHub release, and publishes to RubyGems.
+
+8. **Watch the workflow** and verify the gem appears on RubyGems:
+
+   ```bash
+   gh run watch --workflow=release.yml
+   gem list jekyll-client-search --remote --exact
+   ```
+
+9. **Verify the integration site** builds cleanly against the published
+   gem (update the path dependency to the released version in
+   `../gundestrup.dk` and run `bundle exec jekyll build`).
+
+### What the release workflow does
+
+The [`release.yml`](.github/workflows/release.yml) workflow, triggered by
+pushing a `v*` tag:
+
+1. Checks out the repository at the release tag (`persist-credentials: false`).
+2. Sets up Ruby 3.4.10.
+3. Verifies the tag name matches `v<gem version>` (fails on mismatch).
+4. Verifies `CHANGELOG.md` has a `## X.Y.Z` entry for the version
+   (`rake version:check_changelog` — fails if missing).
+5. Builds the gem (`gem build`).
+6. Creates a GitHub Release and attaches the `.gem` file as a downloadable
+   asset (`softprops/action-gh-release@v2`).
+7. Publishes the gem to RubyGems.org using trusted publishing
+   (`rubygems/release-gem@v1` with OIDC).
+
+CI already validates tests on every push — the release workflow does not
+re-run the test suite. It only builds and publishes. The workflow runs in
+the `release` environment, which must match the environment name
+configured on the trusted publisher.

data/README.md

@@ -25,8 +25,10 @@ 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)
 - [Architecture](#architecture)
 - [Embeddings and incremental indexing](#embeddings-and-incremental-indexing)
 - [Related articles reference](#related-articles-reference)
@@ -138,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
@@ -215,6 +234,160 @@ 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
+expose the document's metadata for CSS-based styling:
+
+| Attribute | Value | Source |
+| --- | --- | --- |
+| `data-source` | Collection label (`posts`, `pages`, `documents`, …) | Generator (always present) |
+| `data-categories` | Space-separated categories | Front matter |
+| `data-tags` | Space-separated tags | Front matter |
+| `data-*` | Any passthrough field (e.g. `data-file-type`, `data-icon-set`) | Config-driven |
+
+**Passthrough fields:** External plugins can expose their data in search
+results by listing field names in `passthrough_fields`. Each listed field is
+forwarded from the document's front matter / data into the search index and
+rendered as a `data-*` attribute on the result `<article>` (field names are
+converted from `snake_case` to `data-kebab-case`).
+
+**Field renaming:** Entries can be strings (same name) or hashes (rename
+`{source => target}`) for integration with other search conventions:
+
+```yaml
+client_search:
+  passthrough_fields:
+    - file_type: doctype      # index as "doctype" instead of "file_type"
+    - icon_url: thumbnail     # index as "thumbnail" instead of "icon_url"
+    - icon_set                # stays as "icon_set"
+  icon_field: thumbnail       # must match the target name
+```
+
+**Auto-injection:** When jekyll-documents is installed and `documents` is
+in the search collections, `file_type`, `icon_url`, and `icon_set` are
+auto-injected into `passthrough_fields` — no manual config needed.
+
+**Icon rendering:** When the configured `icon_field` (default: `"icon_url"`)
+is present in a result, an `<img class="client-search-result-icon">` is
+rendered before the title. Set `icon_field: null` to disable.
+
+**Default icon sizing:** Icons are sized to `1em` (matching the heading's
+font size) with `vertical-align: middle` and a small right margin — they
+auto-scale with the text. The inline styles are self-contained (no CSS
+dependency), so they work with any framework (Bulma, Bootstrap, Tailwind).
+
+Override with CSS:
+
+```css
+/* Make icons larger */
+.client-search-result-icon { width: 1.5em; height: 1.5em; }
+
+/* Fixed pixel sizes (if jekyll-documents' documents.css is included) */
+.client-search-result-icon.icon-x2 { width: 32px; height: 32px; }
+
+/* Theme-aware sizing using jekyll-documents' icon_set */
+.client-search-result[data-icon-set="color"] .client-search-result-icon { width: 1.5em; }
+.client-search-result[data-icon-set="ultra-minimal"] .client-search-result-icon { width: 1em; }
+```
+
+**CSS examples:**
+
+```css
+/* Show a different border color for posts vs pages */
+.client-search-result[data-source="posts"]  { border-left: 3px solid #3273dc; }
+.client-search-result[data-source="pages"]  { border-left: 3px solid #48c774; }
+
+/* Add a badge showing the file type via CSS (no icon_url needed) */
+.client-search-result[data-file-type="pdf"]::before {
+  content: "PDF";
+  background: #ff0000;
+  color: white;
+  padding: 0 0.3em;
+  font-size: 0.7em;
+  margin-right: 0.3em;
+}
+
+/* Show categories as tags */
+.client-search-result[data-categories~="travel"] .title::after {
+  content: " ✈";
+}
+```
+
+This enables per-source icons, file-type badges, category indicators, and
+tag-based styling — all through CSS, with no JavaScript changes needed.
+
 ## Rake tasks
 
 The gem ships reference layouts and includes that you can copy into your
@@ -343,6 +516,47 @@ Each document in the index contains:
 }
 ```
 
+## Indexing custom collections
+
+By default only `posts` are indexed. Add any Jekyll collection to the
+`collections` list to include it in the search index:
+
+```yaml
+client_search:
+  collections:
+    - posts
+    - documents
+```
+
+Each document in the index contains `id`, `title`, `url`, `excerpt`,
+`content`, `categories`, `tags`, and normalized date fields. Collections
+from other plugins work as long as their documents expose these fields.
+
+### Integration with jekyll-documents
+
+[jekyll-documents](https://github.com/gundestrup/jekyll-documents) turns
+files in `assets/documents/` into a browsable `documents` collection with
+titles, categories, and searchable content baked in at build time. To
+include uploaded documents in search results alongside posts:
+
+```yaml
+# _config.yml
+plugins:
+  - jekyll-documents
+  - jekyll-client-search
+
+client_search:
+  collections:
+    - posts
+    - documents
+  related:
+    enabled: true
+```
+
+No additional configuration is needed — `jekyll-documents` bakes
+`categories` (plural array) and searchable `content` into each document
+so the `DocumentBuilder` can index them directly.
+
 ## Architecture
 
 The plugin uses a base runtime + adapter architecture where the base owns
@@ -538,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;
     }
   });