All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading