# Add Search to a Zola Site

Yes. An agent turns on Zola's built-in search index, adds a search page with an elasticlunr script and a menu entry, builds the site and opens a PR.

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

## What the agent does

The agent reads how the site is built before it adds anything, because Zola does half of this job itself and the theme decides the other half. In a site on the Terminimal theme, as in pawroman/zola-theme-terminimal, `config.toml` sets `compile_sass = true`, `generate_feeds = true` with `feed_filenames = ["rss.xml", "atom.xml"]`, a `tags` taxonomy and an `[extra]` table whose `menu_items` list drives the header: `blog`, `tags`, `archive`, `about me` and `github`, each with a `$BASE_URL` placeholder that `templates/macros/menu.html` replaces with `config.base_url`. There is no `build_search_index` key, so Zola writes no index. The README advertises `Absolutely no JavaScript`, `templates/index.html` loads no script, and every other template extends it: `page.html` fills the `content` block, `archive.html` is reached through `content/pages/archive.md`, whose front matter sets `path = "archive"` and `template = "archive.html"`, and `content/pages/_index.md` sets `render = false` so the pages section has no listing of its own.

Zola ships the index. The agent adds `build_search_index = true` to the top of `config.toml` and a `[search]` table with `index_format = "elasticlunr_json"`, `include_title = true` and `include_content = true`, the keys the Zola configuration reference lists. With that, `zola build` writes `search_index.en.json` and `elasticlunr.min.js` into `public/` next to the HTML, named for `default_language`, which the theme already reads to set the `lang` attribute on `html`. The JSON format is chosen over the default `elasticlunr_javascript` so the index is fetched only when someone types, instead of being parsed on every page load. Pages that should not be found get `in_search_index = false` in their front matter: the agent sets it on `content/pages/about.md`, `content/pages/archive.md` and the new search page, so the archive's list of titles does not outrank the posts themselves.

The page follows the archive pattern exactly. `content/pages/search.md` carries `title = "Search"`, `path = "search"` and `template = "search.html"`; `templates/search.html` extends `index.html`, sets the title through `title_macros::title` like `archive.html` does, and fills the `content` block with a `post` div holding an `input` with `id="search"` and a `search-results` container. The script goes in the `extra_body` block that `index.html` already leaves empty at the end of `body`, so no other template changes: one `script` tag for `elasticlunr.min.js` through `get_url` and one for a new `static/search.js`. That file is a trimmed version of the one Zola's own documentation site uses, `docs/static/search.js` in getzola/zola: it loads the index with `elasticlunr.Index.load` on the first keystroke, searches with `title` boosted over `body`, renders at most ten results with a teaser built around the matched terms, and does nothing until the field has text. Styling reuses the theme's `.post` and `.button` classes from `sass/post.scss` and `sass/buttons.scss`, so the colour scheme chosen by `accent_color` applies without a new stylesheet. A sixth entry, `{name = "search", url = "$BASE_URL/search"}`, joins `menu_items`.

Then the agent builds and checks. The sandbox has no Zola, so it installs the Linux build from the v0.23.6 release on GitHub, the current one, and runs `zola build` in the theme's own directory, where `config.toml` and `content/` make the theme its own demo site. It confirms `public/search_index.en.json` exists and contains the posts but not the about or archive pages, runs `zola check` for broken links, serves `public/` on a local port and opens the search page in its own browser: it types `javascript`, a word that appears in the titles of `learning-javascript.md` and `i-dont-like-javascript.md`, and checks those two posts come back and `Zola is nice` does not. The theme's README says it was tested with Zola v0.19.2 and `theme.toml` sets `min_version = "0.11.0"`; the keys used here exist in that range, and the pull request says so.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add full-text search to this Zola site using Zola's built-in search index and elasticlunr. Read config.toml, templates/index.html, templates/archive.html, templates/macros/menu.html, the content directory and the README first. In config.toml set build_search_index = true and a [search] table with index_format = \"elasticlunr_json\", include_title = true and include_content = true, and add a search entry to extra.menu_items. Add content/pages/search.md with path = \"search\" and template = \"search.html\", a templates/search.html that extends index.html with an input#search and a results container in the content block, and load elasticlunr.min.js plus a new static/search.js in the extra_body block only on that page. Base search.js on the one Zola's documentation site uses: fetch search_index.en.json on the first keystroke, boost title over body, show at most ten results with a teaser. Set in_search_index = false on the about, archive and search pages. Install Zola, run zola build and zola check, confirm public/search_index.en.json lists the posts, open the built site in the browser and confirm a search for a word from one post title returns that post. Do not add scripts to any other template. Open a pull request with the commands you ran and their output.",
  "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 changes `config.toml`, adds `content/pages/search.md`, `templates/search.html` and `static/search.js`, and adds one line of front matter to the about and archive pages. Its description quotes the `zola build` summary, the `zola check` result, the list of documents in `search_index.en.json`, and what the browser showed for the test query, with a screenshot from the run's record. No existing template other than the new one changes, and `templates/index.html` still loads nothing on the home page, posts, tags and archive, so the theme's promise holds everywhere except the page that needs the script.

A reviewer checks the menu position, whether they want `include_description` or a `truncate_content_length` for a site with hundreds of long posts, and whether any other page should carry `in_search_index = false`. Pulling the branch and running `zola serve` shows the search page working locally; `zola serve` writes the index like `zola build` does, so there is no separate step. For a site that keeps this theme in `themes/terminimal` rather than as its own repository, the same files go into the site's own `templates/`, `content/` and `static/` directories, where Zola lets them override the theme, and the pull request names that path.

## Run it on every Zola site with no search

A team with several Zola sites sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming one repository in `resources` and carrying a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second one. Each run reads its own theme: a site whose theme already ships a search template gets a note in the pull request instead of a second search box, and a site with `[languages]` in its configuration gets one search page per language, because Zola writes one `search_index.<lang>.json` per language that has `build_search_index` on.

The key's `webhook_url` reports each run the key starts with the pull request URL in `result`, so a script that sent six requests collects six pull requests without polling.

## Why run it on Rush?

Search on a Zola site is two decisions, the index and the page, and both need the real build to check: the index is only written by `zola build`, its contents depend on front matter across the whole `content/` tree, and whether a query finds a post depends on the stemming Zola picked from `default_language`. The agent runs that build in its own sandbox, reads the index it produced, opens the result in a browser and keeps every command and screenshot in the run's record, so the pull request shows a search that works rather than a template that should.

The theme's own constraints shape the change, and the agent reads them from the files: a theme that promises no JavaScript gets the script in the one `extra_body` block on one page, the search page copies the `path` and `template` pattern the archive page already uses, and the menu entry follows the `$BASE_URL` convention of the five that exist. Ten sites on ten themes get ten pull requests, each fitted to its templates.

## Frequently asked questions

### Does this need a search service or a server?

No. Zola writes a static index into `public/` during `zola build`, and the browser fetches it from the same host as the pages. Nothing else is deployed, and there is no account or key.

### Why elasticlunr rather than Fuse?

Zola bundles `elasticlunr.min.js` with the index when `index_format` is one of the two elasticlunr formats, so the page needs no extra dependency, and Zola's own documentation site searches the same way. Setting `index_format = "fuse_json"` instead produces an index for Fuse or tinysearch, and the pull request notes that switch for a site that already loads Fuse.

### Will the theme's no-JavaScript promise still hold?

On every page but one. The script tags live in the `extra_body` block of `templates/search.html` only, and `templates/index.html`, which every other template extends, is unchanged. A reader who wants a search box in the header instead would load the index on every page, and the pull request explains that trade-off without making it.

### How do I keep a page out of the results?

Add `in_search_index = false` to its front matter, or to a section's `_index.md` to exclude everything under it. The pull request does this for the about and archive pages and the search page itself, so a list of every post title does not match every query.

### What about a site in another language?

Zola builds the index for `default_language` and names the file after it, so a French site gets `search_index.fr.json` and the script's fetch path changes with it. The Zola documentation notes that a language other than English also needs the matching lunr stemmer script loaded next to `elasticlunr.min.js`, and the pull request adds that tag when it finds a non-English `default_language`.

## More Zola jobs

- [Add JSON-LD Structured Data to a Zola Site](https://getrush.ai/run/add-structured-data/zola/)
- [Add a Table of Contents to Zola Posts](https://getrush.ai/run/add-table-of-contents/zola/)
- [Add a Typo Check to a Zola Site](https://getrush.ai/run/add-typo-check/zola/)

## The same job on other stacks

- [Add Search to an Eleventy Blog from a Linear Issue](https://getrush.ai/run/add-search/eleventy/)
- [Add Search to a Gatsby Blog from a Linear Issue](https://getrush.ai/run/add-search/gatsby/)
- [Add Search to a Hugo Site](https://getrush.ai/run/add-search/hugo/)

## 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/)
