All jobs

Add Search to an Eleventy Blog from a Linear Issue

Yes. An agent picks up the Linear issue, indexes your Eleventy site with Pagefind after every build, adds a search page, and opens a PR that builds.

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 from the Linear issue and the repository, and reads how the site is built before it adds anything. In a blog made from 11ty/eleventy-base-blog, package.json is "type": "module", depends on @11ty/eleventy ^3.1.7, and its build script is npx @11ty/eleventy while build-ghpages adds --pathprefix=/eleventy-base-blog/; .nvmrc says 22 and engines.node is >=18, and there is a package-lock.json. eleventy.config.js sets the input directory to content and the output to _site, registers a css and a js bundle through addBundle, and adds the navigation plugin, HtmlBasePlugin, the Atom feed plugin and the image transform. _includes/layouts/base.njk builds the header menu from collections.all | eleventyNavigation, inlines the CSS bundle and loads the JS bundle as a module at the end of <body>. Every file under content/blog/ gets tags: ["posts"] and layouts/post.njk from blog.11tydata.js, content/blog.njk lists them through postslist.njk, and _data/metadata.js holds the site title and URL. netlify.toml publishes _site after npm run build, vercel.json only sets trailingSlash, and .github/workflows/gh-pages.yml.sample shows the GitHub Pages deploy the template expects.

It chooses Pagefind, because the issue asks for search without a service and Pagefind builds a static index from the HTML Eleventy already writes. It adds pagefind as a devDependency and hooks it into the build from eleventy.config.js with an eleventy.after handler that uses Pagefind's Node API: create an index, add the _site directory, write the index files to _site/pagefind. Doing it there rather than in an extra npm script means npm run build, npm run build-ghpages and npm start all produce the index, and the deploy commands in netlify.toml and the Pages workflow need no change.

Then it adds content/search.njk: a page on the base layout with an eleventyNavigation entry, so the header loop in base.njk lists it, placed before the Feed entry the config registers at order 4. The page carries a <div id="search">, links /pagefind/pagefind-ui.css, loads /pagefind/pagefind-ui.js and calls new PagefindUI(...) on the element. Because base.njk collects every inline <script> into the page's JS bundle, which runs as a module after the UI script has loaded, the init call can live in that bundle or carry eleventy:ignore; the agent picks one and says which. To keep the index to posts, it adds data-pagefind-body to the article in _includes/layouts/post.njk and data-pagefind-ignore to the previous and next links there, so the archive, tag pages and the home page's post list do not become results of their own. When the site is built with a path prefix it passes the prefix to the UI as its base URL so result links resolve. Drafts never enter the index, because the preprocessor in eleventy.config.js already drops draft pages in build mode.

In its sandbox it runs npm ci, npm run build and npm run build-ghpages, lists _site/pagefind/ to show the UI script, stylesheet and index fragments are there, then serves _site, opens /search/ in its browser, types a word from content/blog/firstpost.md such as agile, and checks that the result links to that post. The screenshot and the build output stay in the run's record and are pasted into the pull request, which links the issue.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "A Linear issue labelled agent says: \"Add a search page to the blog. Visitors should be able to type a word and see the posts that mention it, with no third-party search service.\" Do the work in this Eleventy site. Read package.json, .nvmrc, eleventy.config.js, _data/metadata.js, _includes/layouts/base.njk, _includes/layouts/post.njk, _includes/postslist.njk, content/blog.njk, content/index.njk, netlify.toml and the sample GitHub Pages workflow first. Add pagefind as a devDependency and build its index from eleventy.config.js in an eleventy.after handler so every build, including the path-prefixed one, writes _site/pagefind. Add content/search.njk with a navigation entry and the Pagefind UI, mark the post layout with data-pagefind-body so only posts are indexed, and ignore the previous and next links. Run npm ci, npm run build and npm run build-ghpages, list the pagefind output, serve the site, search for a word from an existing post in the browser and keep the screenshot. Open a pull request that links the issue and shows the build output and the screenshot.",
  "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

What comes back is a pull request on its own branch that changes package.json and package-lock.json to add pagefind, adds the eleventy.after handler to eleventy.config.js, adds content/search.njk, and edits _includes/layouts/post.njk for the body and ignore attributes. The description lists the files Pagefind wrote under _site/pagefind/, quotes the build output of both build scripts, and shows the screenshot of a query matching an existing post. The Linear issue is linked from the pull request.

Before merging, a reviewer checks that the host publishes the whole _site directory, which Netlify and the Pages workflow already do, that the init script is placed the way they prefer relative to the JS bundle, and that a Content Security Policy on the site, if there is one, allows Pagefind to load its WebAssembly. They also decide whether the search entry belongs in the header or only as a page.

Run it on every Linear issue labelled agent

In the Project that holds the blog, add an automation with this prompt and a linear trigger on linear.issue.labeled filtered to the agent label. Each labelled issue starts one run in its own sandbox and ends in one pull request; the issue's text follows the prompt as data, so an issue that asks for tag filtering in results, or for search on the home page rather than its own page, makes its own change. Changes made by an app integration never fire the trigger, so the agent's own comment on the issue starts no further run, and the automation's max_runs_per_hour caps how many issues become runs at once.

From your own server the same run is one POST /o/{org}/sessions per issue, with the repository in resources and the issue's https://linear.app/<workspace>/issue/<ID> URL there too, so Rush reads it through your Linear connection into the prompt. A webhook URL on the API key reports run.completed or run.failed with the session_url when the turn finishes.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

Static search is half build step and half browser, so the only check that counts is a full build followed by a real page load. In its own sandbox the agent runs the same npm run build the host runs, reads the index files it produced, serves the output and types a query in a browser; the commands, the file listing and the screenshot are kept in the run's record, so the pull request shows the feature working rather than describing it.

The change adds one devDependency and no account anywhere, and it is proved by the same build the deploy already runs. The same automation handles every content issue the team labels, one sandbox and one pull request each, with nothing installed on a laptop.

Frequently asked questions

Does it need a search service or an API key?

No. Pagefind reads the HTML in _site after Eleventy writes it and produces a static index next to it. The browser loads only the fragments a query needs, so there is no server, no account and nothing to pay for.

Will search work in dev mode with npm start?

Yes, because the index is written from an eleventy.after handler rather than a separate script, so --serve rebuilds it along with the site. The dev server serves _site/pagefind like any other output.

Does it index the archive, tag pages or drafts?

No. Once data-pagefind-body is on the post layout, pages without it are left out of the index, which covers the home page, the archive and the tag pages. Drafts are dropped before output by the preprocessor already in eleventy.config.js when the run mode is build.

Does it work with the GitHub Pages path prefix?

Yes. The index is built from whatever _site contains, including the prefixed build from npm run build-ghpages, and the search page passes the prefix to the Pagefind UI as its base URL so result links point at the right paths.

More Eleventy jobs

The same job on other stacks

Keep reading