# Add Search to a Jekyll Site

Yes. An agent adds client-side search to your Jekyll site: a Liquid-built JSON index per language, a dependency-free script, localized labels, tests, and a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-search/jekyll/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the site before it adds a search box. In a site laid out like github/choosealicense.com, `_config.yml` runs Jekyll 4.3 (Ruby 4.0.5 in `.ruby-version`) with `jekyll-sitemap`, `jekyll-redirect-from`, `jekyll-seo-tag`, `jekyll-github-metadata` and `jekyll-polyglot` for seven languages (`en`, `fr`, `es`, `pt`, `zh`, `ko`, `ar`), with `assets` in `exclude_from_localization` so scripts are served once from the root. The content is a `licenses` collection: 47 files under `_licenses/` with `title`, `spdx-id`, `nickname`, `description`, `permissions`, `conditions` and `limitations` in front matter, output at `/licenses/:path/`. `licenses.html` shows eight featured ones through `_includes/license-overview.html`, and `appendix.md` tables all of them. `_includes/footer.html` already embeds `window.licenses` (title and SPDX id) on license pages and loads `assets/js/app.js`, which handles tooltips, the copy button and the GitHub repository suggestion. UI strings come from `_data/i18n/<lang>/ui.yml` through `_includes/t.html`, and `spec/i18n_spec.rb` fails if a template asks for a key that `en/ui.yml` does not define. `script/cibuild` runs `rake test` (a build, RSpec, and HTML-Proofer with the Links, Images and Scripts checks) and RuboCop; `.github/workflows/deploy.yml` builds the site itself because polyglot is not on the GitHub Pages plugin list. Nothing on the site searches.

The index is a Jekyll page, `search.json`, with empty front matter and a Liquid loop over `site.licenses` that writes, for each license, `title`, `spdx_id`, `nickname`, `description`, the three rule lists and `url`, with every string passed through `jsonify | replace: '<', '\u003c'` as `footer.html` already does. Descriptions and nicknames are looked up in `site.data.i18n[lang].licenses` first, the way `license-overview.html` does, so the French index holds French text. Because `search.json` is not in `exclude_from_localization`, polyglot renders it once per language, at `/search.json` and `/fr/search.json`, with the URLs already prefixed for that language.

The box lives on `licenses.html` and `appendix.md`, the two pages with `class: license-types`, which is also the condition under which `footer.html` loads `app.js`; the agent adds `assets/js/search.js` under the same condition. The script has no dependencies: it fetches the index for the current language, which `window.choosealicenseI18n.current` already exposes, splits the query into terms, scores title and SPDX id above nickname and description, and renders matches as links in a list with an `aria-live` region, Enter opening the first result. Its three strings, the label, the placeholder and the empty state, are new keys `search_label`, `search_placeholder` and `search_no_results` in `_data/i18n/en/ui.yml`, used through `t.html` so other languages fall back to English until translated and so the i18n spec passes. Styles go in `assets/css/application.scss`, which is compiled compressed, and respect the `dir` attribute `header.html` sets for Arabic.

It runs `bundle exec jekyll build`, opens the index in each language, then `bundle exec rake test`, where HTML-Proofer's Scripts check confirms the new script tag resolves and RSpec checks the new keys, and `bundle exec rubocop` since `cibuild` runs it too. Nothing in `deploy.yml` changes: the new page and script are plain site output.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add client-side search for licenses to this Jekyll site. Read _config.yml, Gemfile, _includes/footer.html, _includes/t.html, _includes/license-overview.html, licenses.html, appendix.md, assets/js/app.js, _data/i18n/en/ui.yml, spec/i18n_spec.rb, script/cibuild and the workflows under .github first. Add search.json at the root with front matter and a Liquid loop over site.licenses that writes title, spdx_id, nickname, description, permissions, conditions, limitations and url per license, using the localized description and nickname from site.data.i18n when present and the same jsonify escaping footer.html uses, so polyglot produces one index per language. Add a search field to licenses.html and appendix.md and a dependency-free assets/js/search.js loaded from footer.html under the same condition as app.js, fetching the index for the current language, scoring title and SPDX id above the other fields, rendering results as links with an aria-live region. Add search_label, search_placeholder and search_no_results to _data/i18n/en/ui.yml and use them through t.html. Style it in assets/css/application.scss with right-to-left in mind. Run bundle exec jekyll build, bundle exec rake test and bundle exec rubocop, then open a pull request that shows the index for two languages.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `search.json` and `assets/js/search.js`, changes `_includes/footer.html` (one script tag), `licenses.html` and `appendix.md` (the field and results list), `_data/i18n/en/ui.yml` (three keys) and `assets/css/application.scss`. Its description shows the first entries of `/search.json` and `/fr/search.json`, quotes the `rake test` and RuboCop output, and lists the three keys for translators.

A reviewer builds the branch, types a license nickname and an SPDX id into the box on the licenses page, and checks that the French page returns French descriptions and French URLs. They read `search.json` for the escaping, since a description containing a `<` must not break the page, and read the script once for what it does with the query before rendering it. Whether the box belongs on the home page too is the one layout question left to them.

No plugin was added, so the site still builds on the workflow it has, and the search needs no service, no index upload and no key.

## Run it on every Jekyll site with no search

A team that runs several Jekyll sites sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming that repository in `resources` with a `request_id` that is a UUID v5 of the repository name, so a retried call returns the run already started. Each run reads its own collections: a blog indexes posts by title, date and excerpt, a docs site indexes pages by heading, and a single-language site gets one index with no polyglot handling.

An automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request adds or renames a license, rebuild the site and post the entry search.json now contains for it as a review" keeps the index honest as the collection grows. The trigger adds the pull request after the prompt and fills in nothing else.

## Why run it on Rush?

Search on a static site is a dozen small decisions that are easy to get subtly wrong: what goes in the index, how it is escaped, what a seven-language build does with one more page, which strings the translation spec will reject. The agent makes them against the real site in its own sandbox, runs the site's own build, specs and link checker, and keeps the output with the pull request.

A reviewer reads a Liquid file, one script and three YAML keys. A team with many Jekyll sites starts the same request across all of them, each in its own sandbox with its own Ruby and plugins.

## Frequently asked questions

### Why not a plugin or a hosted service?

This site already builds outside GitHub Pages because of polyglot, so a plugin would work, but the index is a Liquid page and the matching is a few dozen lines, which is less to maintain than a gem or an account. A hosted index would also need a key in the build and a crawl per language.

### How does it handle the languages?

`search.json` is an ordinary page, so polyglot renders it once per language with localized descriptions and prefixed URLs, and the script fetches the one for the language it is running in. The three UI strings go through the same `t.html` lookup as the rest of the site and fall back to English.

### Will the tests catch a mistake?

The site's own suite does most of it: HTML-Proofer checks the script tag resolves, `spec/i18n_spec.rb` checks every `t.html` key exists in `en/ui.yml`, and RuboCop runs on the Ruby. The agent runs all three before opening the pull request.

### Does it search the license text?

Not by default. The index holds the summary fields and the rule tags, which is what people search for, and stays small. Adding the body is a Liquid change if the team wants it, at the cost of a larger file per language.

## More Jekyll jobs

- [Add a Sitemap to a Jekyll Site](https://getrush.ai/run/add-sitemap/jekyll/)
- [Add JSON-LD Structured Data to a Jekyll Site](https://getrush.ai/run/add-structured-data/jekyll/)
- [Add a Table of Contents to Jekyll Posts](https://getrush.ai/run/add-table-of-contents/jekyll/)

## The same job on other stacks

- [Add Search to a Pelican Blog](https://getrush.ai/run/add-search/pelican/)
- [Add Search to a VitePress Blog With a Custom Theme](https://getrush.ai/run/add-search/vitepress/)
- [Add Search to a Zola Site](https://getrush.ai/run/add-search/zola/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
