All jobs

Add Search to a VitePress Blog With a Custom Theme

Yes. An agent turns on VitePress local search, wires its search box into your custom theme's layout, builds the index, checks it in a browser, and opens a PR.

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 theme before touching the config, because search in VitePress is half a build option and half a navbar component. In a blog laid out like vuejs/blog, .vitepress/theme/index.ts exports an object with only Layout, not an extension of DefaultTheme, and Layout.vue draws its own nav with a logo, a GitHub link, an RSS link and a link to vuejs.org, then renders Home, Article or NotFound from useData(). There is no themeConfig in .vitepress/config.ts at all; it sets title, description, cleanUrls: true, a head list and buildEnd: genFeed. package.json pins vitepress at ^1.3.4 under packageManager pnpm@9.8.0, with Tailwind 3.4.10 and @tailwindcss/typography for the article styling, and pnpm-lock.yaml resolves VitePress with @algolia/client-search as an optional peer that nothing uses.

It then reads what there is to index: sixteen posts under posts/, each with title, date and author in front matter and an excerpt above a --- line, collected by createContentLoader('posts/*.md') in posts.data.ts, and a root index.md whose index front matter makes Layout render the post list. The home page should not be a search hit, since every result on it is a post that is already indexed under its own URL.

The config change is themeConfig.search with provider: 'local', which makes VitePress build a MiniSearch index from each page's rendered content at build time and load it in the browser on first use, with the default searchOptions of fuzzy 0.2, prefix matching and a title boost of 4. Because the custom theme has no navbar, the agent imports VPNavBarSearch from vitepress/theme, the component the default theme uses, and places it in Layout.vue's nav beside the RSS link; that component reads the search config from useData() and lazy-loads the local search box when the button or its keyboard shortcut is used. The box relies on the default theme's --vp-* CSS variables, which this theme never loads, so the agent imports the default theme's variables stylesheet in theme/index.ts and checks that Tailwind's preflight and the .dark class the layout already uses do not fight it. index.md gets search: false in its front matter.

In its sandbox the agent runs pnpm install --frozen-lockfile and pnpm build, lists .vitepress/dist/assets/chunks/ to show the generated search index chunk and its size, then runs pnpm preview, opens the site in a browser, presses the shortcut, types vitepress and screenshots the results pointing at the vitepress-1.0 post with the matching heading highlighted. It repeats the query with the .dark class on to show the box is readable in both modes, and runs pnpm dev once to confirm the index is served there too.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add search to this VitePress blog. Read .vitepress/config.ts, .vitepress/theme/index.ts, .vitepress/theme/Layout.vue, .vitepress/theme/posts.data.ts, .vitepress/theme/style.css, index.md, two files under posts/, package.json and the vitepress entry in pnpm-lock.yaml first. Turn on the local search provider in themeConfig, and since the theme is a custom Layout rather than an extension of the default theme, import the default theme's navbar search component from vitepress/theme and place it in the Layout's nav beside the existing links, loading whatever default theme styles it needs. Exclude the home page from the index with front matter. Build the site, show the generated index chunk in the output directory, serve the build and search for a word from one post's heading in a browser, screenshotting the result in light and dark mode. Open a pull request with the screenshots, the build output and the index size. Do not switch the theme to the default theme and do not change 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

The pull request changes .vitepress/config.ts, .vitepress/theme/index.ts, .vitepress/theme/Layout.vue and the front matter of index.md, and nothing else; pnpm-lock.yaml is untouched because no package is added. Its description pastes the pnpm build output, the listing of .vitepress/dist/assets/chunks/ with the search index chunk and its size, and two screenshots of a query returning a post with its heading highlighted, one in light and one in dark mode.

A short paragraph explains the two halves of the change: the config line that builds the index, and the imported navbar component that gives the custom layout a button and shortcut to open it, with the stylesheet import that makes the box readable without the default theme.

Before merging, a reviewer checks the button's place in the nav on a narrow viewport, decides whether excerpts or whole posts should be indexed, and considers a locales translation of the button label if the blog ever adds a second language.

Run it on every VitePress site without a search box

A team with several VitePress sites sends this body once per repository from its own server, each a POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retry returns the run already started. Each run reads its own theme: a site that extends DefaultTheme needs only the config line, since its navbar already renders the search button, and a site with an Algolia block in themeConfig is left alone and reported.

A webhook_url on the key reports each run.completed with the pull request in result, and a run.failed names a site whose build broke on the change, for instance one whose custom theme shadows a --vp-* variable the search box needs. Nothing rebuilds the index later: every pnpm build regenerates it from the posts of that day.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Static search is only as real as the built index and the component that opens it, and in a custom theme neither comes for free: the config line alone produces an index no page can reach. The agent builds in its own sandbox with the pinned pnpm, reads the output directory, and types a query in a browser, so the pull request shows a result list rather than a config diff.

The choices are the repository's: no DefaultTheme to extend, Tailwind styling that the search box's variables must coexist with, and a home page that should not compete with the posts it lists. The build log, the chunk listing and the screenshots stay with the run.

Frequently asked questions

Why is a config line not enough on this site?

Because .vitepress/theme/index.ts exports a bespoke Layout and never uses the default theme, so there is no navbar to render the search button. provider: 'local' still builds the index; the agent imports VPNavBarSearch from vitepress/theme into Layout.vue so a visitor can open it.

Does it add a dependency or send queries to a service?

No. Local search ships inside VitePress, builds a MiniSearch index during pnpm build, and runs queries in the browser. The @algolia/client-search peer in the lockfile stays unused, and no key or account is involved.

Will the search box look right next to Tailwind?

The box is styled with the default theme's --vp-* variables, which this theme never defines, so the agent imports the default theme's variables stylesheet and checks the result in both colour modes in a browser. The screenshots in the pull request are the evidence; a clash with Tailwind's preflight would show there.

How do I keep a page out of the index?

Add search: false to its front matter, which the agent does for index.md. A custom _render function in the search options can filter further, but this site needs none.

More VitePress jobs

The same job on other stacks

Keep reading