Websites

Docusaurus search

Add Hayfork search to a Docusaurus site with one theme. Visitors get a search box in the navbar and a ⌘K dialog, with results that link to the right page and section. Hayfork crawls your published site, so there is no index to build in CI and no application to wait on.

Add your docs as a website source

In the console, add your docs address under Data sources, then create a collection that searches it. Docusaurus publishes a sitemap, so the crawler finds every page. See Website sources for scope and page limits.

Create a website key

A website key can only search, only the collections you choose, and only from the websites you list, so it is safe in your page source. Include http://localhost:3000, the Docusaurus development address, while you build:

curl https://api.hayfork.dev/api-keys \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Docusaurus search",
    "scopes": ["search"],
    "allowed_origins": ["https://docs.example.com", "http://localhost:3000"],
    "collection_ids": ["COLLECTION_ID"],
    "expires_in_days": 365
  }'

The response includes the key once, in a key field. Website keys has the rules for listing websites.

Install the theme
```
npm install docusaurus-theme-hayfork
```

Add it to your config

In docusaurus.config.js:

export default {
  themes: [
    [
      "docusaurus-theme-hayfork",
      {
        key: "YOUR_WEBSITE_KEY",
        collection: "COLLECTION_ID",
      },
    ],
  ],
};

Start the site with npm start. The search box appears at the right of the navbar.

Options

Option	Default	Notes
`key`	required	A website key.
`collection`	required	The collection id to search. It must be one of the key's collections.
`placeholder`	`Search`	Text in the search box and the dialog.
`theme`	`auto`	`light`, `dark`, or `auto` to follow the visitor's system setting.
`results`	`8`	Results to show, 1 to 20.
`shortcut`	`true`	`false` turns off the `⌘K`, `Ctrl K` and `/` shortcuts.

To move the search box, add a search item to the navbar, such as { type: "search", position: "left" } in themeConfig.navbar.items.

Moving from Algolia DocSearch

Only one theme can provide the search bar, so remove Algolia's before adding Hayfork's:

Delete the algolia block from themeConfig. The classic preset adds Algolia's theme only when that block is present.
If @docusaurus/theme-search-algolia is listed under themes, remove it, and uninstall the package.
Keep any { type: "search" } navbar item. Hayfork's theme fills the same slot.

Hayfork indexes the published pages, so you do not need DocSearch's crawler config or an index upload step. Hayfork vs Algolia compares the two in more detail.

Keeping results current

After you publish new pages, press Sync on the website source in the console. A re-crawl updates pages in place and does not count against your document limit. To sync from a deploy pipeline, call POST /crawl with the source's data_source_id, as described in Website sources.

Troubleshooting

What you see	What to do
The build stops with `Set both "key" … and "collection"`	Add both options to the theme entry in `docusaurus.config.js`.
No search box, or Algolia's box instead	Another search theme is still installed. Remove it as in Moving from Algolia DocSearch.
"This search box is not set up for this website."	The page's exact address, with `https://` and any `www.`, is missing from the key's websites. In development it must be `http://localhost:3000`, or the port you start Docusaurus on.
The box stays light when the site is switched to dark	`auto` follows the visitor's system setting, not the Docusaurus colour toggle. Set `theme` to match a site that is always light or always dark.

For other messages, see Search widget troubleshooting. The theme's source is at github.com/hayfork-dev/docusaurus-theme-hayfork.