All jobs

Add Search to a Gatsby Blog from a Linear Issue

Yes. An agent takes a labelled Linear issue, builds a static search index from your Markdown posts at build time, 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 reads the issue, then reads how posts reach the page. In a blog shaped like gatsbyjs/gatsby-starter-blog, package.json pins gatsby 5.14 with gatsby-source-filesystem on content/blog, gatsby-transformer-remark with the images, iframe and Prism plugins, gatsby-plugin-feed for /rss.xml and gatsby-plugin-manifest; the only dev dependency is Prettier and the test script exits with a reminder to write tests. gatsby-node.js creates one page per post from an allMarkdownRemark query, adds a slug field in onCreateNode and declares the Frontmatter type with title, description and date in createSchemaCustomization. src/pages/index.js lists every post with its excerpt, and src/components/layout.js renders the header, main and footer. No search plugin is installed and no page offers one.

Rather than add a plugin, the agent builds the index where the data already is. In gatsby-node.js it adds an onPostBuild hook that runs one allMarkdownRemark query for title, description, excerpt, date, fields.slug and rawMarkdownBody, strips the Markdown body to text, and writes public/search-index.json, the same way the feed plugin writes rss.xml. A new src/pages/search.js renders a search field inside Layout, fetches the index on the first keystroke, and ranks posts with flexsearch, the one new dependency, matching on title, description and body with the matched post rendered through the same post-list-item markup index.js uses, so the existing style.css applies. The query is mirrored into the page's ?q= parameter so a result link can be shared, and layout.js gains a link to /search beside the site title.

During gatsby develop there is no onPostBuild, so the agent also registers the same writer in onCreateDevServer, which lets the search page work locally without a production build. createSchemaCustomization already declares the frontmatter fields, so a post without a description still indexes with its excerpt and the build does not fail on a missing field.

Because the repository has no tests and no CI workflow, the proof is the build itself: the agent runs gatsby build, reads public/search-index.json to show one entry per post under content/blog, serves the site with gatsby serve, and opens /search?q= with a word from one post in the sandbox browser to confirm the matching post is listed. It runs npm run format so Prettier leaves nothing to fix, and adds a line to README.md about the search page.

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 in the title, description or body, without a third-party search service.\" Do the work in this repository. Read package.json, gatsby-config.js, gatsby-node.js, gatsby-browser.js, src/pages/index.js, src/templates/blog-post.js, src/components/layout.js, src/components/seo.js and the posts under content/blog first. In gatsby-node.js add an onPostBuild hook, and the same writer in onCreateDevServer, that queries allMarkdownRemark for title, description, excerpt, date, slug and rawMarkdownBody, strips the body to text and writes public/search-index.json. Add src/pages/search.js with a search field that fetches that file on the first keystroke and ranks posts with flexsearch over title, description and body, renders results with the same post-list-item markup index.js uses, and mirrors the query into a q parameter. Add a link to /search beside the site title in src/components/layout.js. Add flexsearch as the only new dependency. Run gatsby build, show the contents of public/search-index.json, serve the site with gatsby serve and check /search with a word from one post in the browser, run npm run format, and put the results and a screenshot in the pull request description. Add a line about the search page to README.md. Do not change gatsby-config.js or any post.",
  "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 with the two hooks in gatsby-node.js, the new src/pages/search.js, the link in src/components/layout.js, flexsearch in package.json and package-lock.json, and a README line. The description shows the generated public/search-index.json with one entry per post, the gatsby build summary, and a screenshot of /search listing the post that matches the query the agent typed in the sandbox browser.

The repository has no workflow, so there is no check to wait for. The agent's own gatsby build and gatsby serve run from the transcript are the evidence, with the commands and their output kept on the run. The agent pushes one commit for the index and one for the page and link.

A reviewer checks that the index holds no field the pages do not already render, that the fetch happens on the first keystroke rather than on every page load, that the result markup matches index.js so the stylesheet applies, and that a post without a description still appears. Then they open /search on the preview.

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 its own run in its own sandbox and ends in its own pull request; the issue's text follows the prompt as data, so an issue that asks for tag filtering in the results or a different placement of the link makes its own change.

Changes made by an app integration never fire the trigger, so the agent's own comments on the issue start no further runs, and the automation's max_runs_per_hour caps how many issues become runs at once.

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

Why run it on Rush?

Search on a static site lives half at build time and half in the browser, so the only check that counts is a full build followed by a real page load. In a Rush sandbox the agent runs gatsby build, reads the index file it produced, serves the site and types the query in a browser; those commands, the file and the screenshot are kept in the run's transcript, so the pull request shows the result rather than claiming it.

The change adds one dependency and no external service, and it is proved by the same gatsby build the deployment runs. The same automation handles every content issue the team labels, one sandbox and one pull request each.

Frequently asked questions

Why not a Gatsby search plugin?

The data is already in the allMarkdownRemark query that gatsby-node.js and index.js run, so a hook that writes one JSON file needs no plugin and nothing to keep updated when Gatsby moves. The only addition is flexsearch for ranking in the browser.

Does the index grow with every post?

Yes, by one entry with the post's title, description, date, slug and body text. It is fetched once, on the first keystroke, and cached by the browser like any other static file, so the home page and post pages do not pay for it.

Does search work in gatsby develop?

Yes. onPostBuild runs only for gatsby build, so the agent registers the same writer in onCreateDevServer, which runs when gatsby develop starts. New posts are picked up on the next restart in development and on the next build in production.

Will the RSS feed or the manifest change?

No. gatsby-config.js is untouched, so gatsby-plugin-feed and gatsby-plugin-manifest keep their options. The search page is a normal page under src/pages, so it gets the site's Seo head and layout like the others.

More Gatsby jobs

The same job on other stacks

Keep reading