All jobs

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

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

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 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

The same job on other stacks

Keep reading