# Add Search to a Hugo Site

Yes. An agent adds a Pagefind index to your Hugo build, a search page that uses it, a nav entry and a CI step, then opens a PR you can read.

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

## What the agent does

The agent starts by reading how the site is put together, because a Hugo search feature lives in three places: the build, the templates and the deploy. In a site built on the Bear Blog theme, as in janraasch/hugo-bearblog's `exampleSite`, `hugo.toml` sets `theme = 'hugo-bearblog'`, `disableKinds = ["taxonomy"]`, a `blog` permalink of `/:slug/` and `enableRobotsTXT = true`. The theme's `theme.toml` lists `no javascript` among its features, and its `layouts/_default/baseof.html` loads no script at all: it renders `partial "header.html"`, a `main` block, a footer, and two empty partials the README reserves for the site owner, `custom_head.html` and `custom_body.html`. The menu is built in `layouts/partials/nav.html` from `.Site.Menus.main`, which `content/_index.md` joins at weight 1 and `content/blog/_index.md` at weight 100. The theme repository's `.github/workflows/ci.yml` builds with `peaceiris/actions-hugo@v3.2.1` and the command `hugo --minify --gc --destination ../public --source ./exampleSite --themesDir ../..`, uploads `./public` as an artifact and deploys it with `peaceiris/actions-gh-pages@v4.1.0`.

The index comes from Pagefind, which reads the finished HTML rather than the Markdown, so nothing in the content changes. The agent adds one command after the Hugo build, `npx -y pagefind --site public --root-selector main`, which writes the index and its scripts under `public/pagefind/`. The root selector matters on this theme: without it Pagefind indexes everything inside `body`, so the site title and the menu would match every query. Pointing it at `main` keeps only each post's text, the same effect as a `data-pagefind-body` attribute but without copying `baseof.html` out of the theme. Because the theme sets `lang` on the `html` element from `.Site.Language.Locale`, Pagefind picks the right stemming without configuration.

The search page is one content file and one template. `content/search.md` carries `menu = "main"` with a weight between the home page and the blog, plus `layout = "search"`, so Hugo renders it with a new `layouts/_default/search.html`. That template defines the `main` block with the Pagefind Component UI: a stylesheet link to `/pagefind/pagefind-component-ui.css`, a module script for `/pagefind/pagefind-component-ui.js`, and the inline building blocks `<pagefind-input>`, `<pagefind-summary>` and `<pagefind-results>`, which connect to each other when they share a page. Loading the script from the search template alone, rather than from `custom_head.html`, keeps every other page as script-free as the theme promises. For a site that wants a search box in the header instead, the same script plus `<pagefind-modal-trigger>` and `<pagefind-modal>` in `custom_body.html` gives a modal on every page, and the pull request shows that variant in a comment without enabling it.

Then the agent builds and looks. It runs `hugo --minify` and the Pagefind command in its sandbox, checks that `public/search/index.html` and `public/pagefind/` exist, opens the built site in its own browser, types a word that appears only in `blog/markdown-syntax.md` and confirms that post is the result. `hugo server` does not run Pagefind, so the pull request documents the local loop, `hugo && npx -y pagefind --site public --serve`, which serves the built site with the index on a local port. In the workflow it adds a Node setup step and the Pagefind command between the build and the artifact upload, so the deployed site carries the index too.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add full-text search to this Hugo site with Pagefind. Read hugo.toml, the theme's layouts/_default/baseof.html, layouts/partials/nav.html, custom_head.html and custom_body.html, the content directory and .github/workflows first. Add a content/search.md page in the main menu with layout search, and a layouts/_default/search.html template that loads /pagefind/pagefind-component-ui.css and /pagefind/pagefind-component-ui.js as a module and renders pagefind-input, pagefind-summary and pagefind-results. Do not add scripts to any other page. Run the index as npx -y pagefind --site public --root-selector main after the Hugo build, add that step with a Node setup to the GitHub Actions workflow before the artifact upload, and document the local command hugo && npx -y pagefind --site public --serve in the README. Build the site, run Pagefind, open the built site in the browser and confirm a search for a word from one blog post returns that post. Open a pull request with the commands 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 adds `content/search.md`, `layouts/_default/search.html` and a README section, and changes `.github/workflows/ci.yml` to install Node and run Pagefind after `hugo`. Its description quotes the Hugo build output, the Pagefind summary line that reports how many pages it indexed, and what the browser showed for the test query, with a screenshot of the results list from the run's record. The theme directory is untouched: no file under `themes/` or the theme module changes, because the override points go through `layouts/` and the CLI flag.

A reviewer checks three things: that the search page sits where they want it in the menu, that the weight they would choose matches, and that the workflow's Pagefind step runs on the same `public` directory the build writes to. Pulling the branch and running the documented local command shows the search page working on their machine before merge. Nothing about the deploy changes; the artifact just contains one more directory.

## Run it on every Hugo site without search

A team that keeps several Hugo 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. Each run reads its own theme: a site on a theme that already ships a search partial gets a note in the pull request instead of a second search box, and a site that builds with a `Makefile` rather than Actions gets the Pagefind command in the `Makefile`.

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

## Why run it on Rush?

Search on a static site is a build step as much as a feature: the index has to be produced from the same HTML the deploy ships, on every deploy, or it goes stale on the first new post. The agent runs the real build in its own sandbox, runs Pagefind on its output, opens the result in a browser and keeps every command and screenshot in the run's record, so the pull request shows the feature working rather than describing it.

The theme's own constraints shape the change, and the agent reads them from the files: a theme that advertises no JavaScript gets the script on one page, the CLI's root selector replaces a template override, and the menu weight follows the two entries that already exist. Ten sites with ten themes get ten pull requests, each fitted to its layouts.

## Frequently asked questions

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

No. Pagefind writes a static index into `public/pagefind/` and the browser downloads only the fragments a query needs. There is nothing to host beyond the files the site already deploys, and no key or account.

### Why does hugo server not show search results?

The index is built from the finished HTML, after Hugo runs, and `hugo server` never writes `public/`. The pull request documents the two-command loop, `hugo` followed by `npx -y pagefind --site public --serve`, which serves the built site with its index for checking locally.

### Will it change the theme?

No. The search template and page live in the site's own `layouts/` and `content/` directories, and the `--root-selector main` flag limits the index without touching `baseof.html`. A theme update later does not conflict with the change.

### Can the search box go in the header instead of its own page?

Yes. The same script with `<pagefind-modal-trigger>` and `<pagefind-modal>` in `custom_body.html` opens a modal from every page. The pull request describes that variant and leaves it off by default, because it loads the script on every page of a theme that otherwise ships none.

### What about a multilingual site?

Pagefind reads the `lang` attribute the theme sets on the `html` element and keeps one index per language, so each language searches its own pages. A site with `[languages]` in `hugo.toml` needs the search page under each language's content directory, and the pull request adds one per language it finds.

## More Hugo jobs

- [Add Social Cards to a Hugo Site](https://getrush.ai/run/add-social-cards/hugo/)
- [Add JSON-LD Structured Data to a Hugo Documentation Site](https://getrush.ai/run/add-structured-data/hugo/)
- [Add a Table of Contents to a Hugo Blog](https://getrush.ai/run/add-table-of-contents/hugo/)

## The same job on other stacks

- [Add Search to a Jekyll Site](https://getrush.ai/run/add-search/jekyll/)
- [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/)

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