# Add Search to a Pelican Blog

Yes. An agent adds a Pagefind index to a Pelican blog's build, a search page in the theme and a menu entry, checks the results in a browser and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-search/pelican/). 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 blog is built before it adds anything, because Pelican has no search of its own and the theme decides where a search box can go. In a site like getpelican/pelican-blog, `pelicanconf.py` sets `PATH = "content"`, `THEME = "themes/notmyidea"`, `DEFAULT_PAGINATION = 5`, a `MENUITEMS` tuple of three entries (`documentation`, `contribute` and `gratitude`, the last pointing at `/pages/gratitude.html`) with `DISPLAY_PAGES_ON_MENU = False`, and a `MARKDOWN` block with the `toc`, `codehilite` and `admonition` extensions. `publishconf.py` imports it, sets `SITEURL = "https://blog.getpelican.com"` and `DELETE_OUTPUT_DIRECTORY = True`. There is no `PLUGINS` setting and no `plugins/` directory. The `Makefile` builds with `pelican $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE)` for `html`, the same with `publishconf.py` for `publish`, and `upload` rsyncs `output/` to the server; `develop_server.sh` runs `pelican -r` for the dev loop. The content is twenty-two reStructuredText and Markdown files under `content/news/` and `content/pages/`, and the theme's `base.html` renders a `header#banner` with the menu, the `content` block and a `section#extras` with the blogroll and social links.

The agent picks Pagefind because it indexes the finished HTML after the build, so nothing in Pelican's generator changes and no plugin is installed: `npx --yes pagefind --site output` reads every page in `output/`, writes the index and its `pagefind.js`, `pagefind-ui.js` and `pagefind-ui.css` into `output/pagefind/`, and the browser fetches only the index fragments a query needs. To keep the index to post bodies, it adds `data-pagefind-body` to the `div.entry-content` in `article.html` and `page.html`; once any page carries that attribute, Pagefind indexes nothing on pages without it, so the paginated index pages, the archives and the tag lists stay out and each post is found once. The `section#extras` in `base.html` and the `article_infos.html` byline get `data-pagefind-ignore`, so a query for an author's name does not match every page.

The search page follows the pattern the menu already uses. `content/pages/search.rst` carries a `:template: search` field, so Pelican writes it to `output/pages/search.html` like the gratitude page, and `MENUITEMS` gains a `("search", "/pages/search.html")` entry. `themes/notmyidea/templates/search.html` extends `base.html`, puts a `div#search` in the `content` block, and loads `{{ SITEURL }}/pagefind/pagefind-ui.css` and `{{ SITEURL }}/pagefind/pagefind-ui.js` the way `base.html` already loads `theme/css/{{ CSS_FILE }}`, then calls `new PagefindUI({ element: "#search", showSubResults: true })`. Because `SITEURL` is empty in `pelicanconf.py` and the full host in `publishconf.py`, the paths work in both builds. The `Makefile` gets a `search` target that runs the Pagefind command on `$(OUTPUTDIR)`, and `html` and `publish` call it after Pelican, so `make upload` ships the index.

Then it builds and checks. The repository has no requirements file, so the agent installs `pelican` and `markdown` (one post, `namespace-plugins.md`, is Markdown), runs `make publish`, runs Pagefind, and confirms `output/pagefind/` holds the index and that the entry count matches the number of posts and pages rather than every generated file. It serves `output/` on a local port and opens `/pages/search.html` in its own browser: it types `namespace` and checks the plugin migration post comes back, types a word from the Pelican 4.7 release notes and checks that post comes back, and types an author's name and checks that no page matches on the byline alone. While reading the `Makefile` it notes that `serve` still runs `python -m SimpleHTTPServer`, a Python 2 module, and lists that in the pull request rather than changing it.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add search to this Pelican blog using Pagefind. Read pelicanconf.py, publishconf.py, the Makefile, develop_server.sh, the content directory and every template under themes/notmyidea/templates first. Add a search target to the Makefile that runs npx --yes pagefind --site on the output directory after Pelican, called by both the html and publish targets. Add data-pagefind-body to the entry content in article.html and page.html and data-pagefind-ignore to the extras section and the byline so only post and page bodies are indexed. Add content/pages/search.rst with a search template, a templates/search.html that extends base.html with a div#search and the Pagefind UI script and stylesheet loaded through SITEURL, and a search entry in MENUITEMS. Install pelican and markdown, run make publish and the Pagefind command, confirm the index covers the posts and pages, serve the output and test three queries in your browser, and open a pull request that lists what you checked and anything in the Makefile you noticed but left alone.",
  "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

A pull request that changes `pelicanconf.py` (one menu entry), the `Makefile` (a `search` target and two call sites), `article.html`, `page.html`, `base.html` and `article_infos.html` (the two Pagefind attributes), and adds `content/pages/search.rst` and `templates/search.html`. No generated file is committed: `output` is already in `.gitignore`, and the index is rebuilt on every `make publish`. The description lists the index's entry count, the three queries and what each returned, and the dev-server note.

A reviewer checks that the attributes sit on the elements they want indexed, that the menu entry's path matches `PAGE_SAVE_AS`, and that the Pagefind version is pinned in the `Makefile` if they want builds to be reproducible. After merge, the next `make upload` publishes the search page along with the index, and the search box works on the live site without any server-side component.

## Run it on every terminal hand-off

A maintainer who has just written a release post starts this from the terminal with this body and the repository in `resources`, and keeps writing. The run reads the real theme and the real `Makefile`, so the search page uses the blog's own base template and the index is built by the same target that already publishes the site.

Send a `request_id`, a UUID, with the body so a retried start returns the run it already began. When the turn ends, `GET /o/{org}/sessions/{id}` names the pull request, and a follow-up to the same session can ask for the search box in the banner instead of a page, or for the index to include the gratitude page's content.

## Why run it on Rush?

The edits are small; the work is proving the index covers the right pages, which means a full Pelican build, a Pagefind run and a browser. The agent does all of that in its own sandbox and keeps every command, its output and the pages it opened in the run's record, so the pull request shows which queries matched which posts rather than describing a search box that was never typed into.

The same run fits any Pelican site: a theme with a sidebar where the box belongs in `base.html`, a site that already runs a plugin and wants the index built by a `pelican` signal handler instead of the `Makefile`, or a multilingual site with `i18n_subsites` where each language needs its own index. Each gets a search page derived from its own templates and a check against its own content.

## Frequently asked questions

### Why Pagefind rather than a Pelican plugin?

A plugin runs inside the generator and has to be installed with the right Pelican version on every machine that builds the site. Pagefind runs after the build on the HTML every static host serves anyway, so the blog's Python setup is untouched, and the browser downloads only the parts of the index a query needs instead of the whole index on page load.

### Does the dev server pick up search?

`develop_server.sh` runs `pelican -r`, which regenerates pages as files change but never runs Pagefind, so the search page in the dev loop shows no results until `make search` runs once. The pull request says so, and a follow-up can wire Pagefind into the script if the team wants it live while writing.

### Will the index include drafts or the 404 page?

Only pages whose template carries `data-pagefind-body` are indexed, so the not-found page is included if `page.html` renders it and excluded by a `data-pagefind-ignore` on that page alone. Drafts are written to `output/drafts/` by Pelican, so the run excludes that directory with Pagefind's glob option and the pull request shows the entry count without them.

### Can I keep the site free of JavaScript?

Only the search page loads the Pagefind scripts; every other page gets two attributes and nothing else. If the team wants no script anywhere, the alternative is a form that posts to an external search engine, which the pull request mentions as the trade-off.

## More Pelican jobs

- [Add a Sitemap to a Pelican Site](https://getrush.ai/run/add-sitemap/pelican/)
- [Add Structured Data to a Pelican Blog](https://getrush.ai/run/add-structured-data/pelican/)
- [Add a Typo Check to a Pelican Site](https://getrush.ai/run/add-typo-check/pelican/)

## The same job on other stacks

- [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/)
- [Add Search to an Eleventy Blog from a Linear Issue](https://getrush.ai/run/add-search/eleventy/)

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