Right, Algolia DocSearch. Let’s get this out of the way: this is the “it just works” option, provided you qualify for the free tier. It’s a hosted service Algolia generously offers for open-source and documentation sites. Think of it as the concierge of search: they handle the heavy lifting of indexing, updating, and hosting the search engine itself. You just plug in the UI.

The magic—and the potential pitfall—happens on their servers. A custom crawler (which they run) visits your site according to a schedule you configure, sucks up all the content, and pushes it to an Algolia index. Your JavaScript then queries that index directly. This is fantastic because it means no build-time slowdowns and your search index is always up-to-date with your latest published content. The trade-off? You surrender control. You can’t index unreleased content, and your search is wholly dependent on their crawler and infrastructure.

The DocSearch Application Process

First, you have to see if you qualify. Head over to the DocSearch page and fill out the form. This isn’t a technical step, but a bureaucratic one. Your site needs to be public documentation, preferably for an open-source project. If you’re approved, they’ll email you two pieces of golden information: an apiKey and an indexName. Guard these. The apiKey is a search-only key, which is safe to expose in your frontend code, but you still don’t want to share it publicly for obvious reasons.

Plugging It Into Hugo

Once you have your credentials, the integration is dead simple. You don’t install an npm package; you just include their JavaScript and CSS, then initialize the widget with your config. The classic way is to plop this into your layouts/partials or right before your closing </body> tag.

<!-- Load the Algolia DocSearch library and styling -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>

<!-- Initialize it -->
<script>
docsearch({
  appId: 'YOUR_APP_ID', // You get this from them; it's often a string like "ABC123DEF"
  apiKey: 'YOUR_SEARCH_API_KEY', // The search-only key they provided
  indexName: 'YOUR_INDEX_NAME',   // Your index name, e.g., "hugo-docs"
  container: '#search-box', // The CSS selector for your search input container
  debug: false // Set to true if you want to see what's happening in the console
});
</script>

You’ll also need an element on your page for the search box to anchor to:

<div id="search-box"></div>

The widget takes over from there, injecting a fully-functional, beautifully designed search input that displays results as you type.

The Configuration Dance: docsearch.json

This is where you tell Algolia’s crawler how to behave. When you’re accepted, they’ll create a basic one for you, but you can (and should) submit your own for fine-tuning. You host this file at /docsearch.json on your live site.

The config is a JSON file that dictates what to crawl, what to scrape, and how to structure the records. The selectors key is the most important. You’re essentially giving the crawler a CSS-based map of your documentation.

{
  "index_name": "your_index_name",
  "start_urls": [
    "https://your-docs-site.com/"
  ],
  "selectors": {
    "lvl0": {
      "selector": ".docs-nav h2", // The main section title, e.g., "Guides"
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": "h1", // The page title
    "lvl2": "article h2", // Sub-section headers
    "lvl3": "article h3",
    "lvl4": "article h4",
    "text": "article p, article li, article code" // The actual body content to search
  },
  "selectors_exclude": [".docs-footer", ".hidden"] // Tell it what to ignore
}

Getting these selectors right is more art than science. You’ll need to inspect your live site’s DOM structure. A common pitfall is being too broad or too narrow. If your lvl0 selector is wrong, all your results will be categorized incorrectly. It’s a frustrating process of pushing a config update, waiting for a crawl (which can take hours), and checking the results in their dashboard.

When the Magic Fades: The Big Caveats

Let’s be brutally honest about the downsides.

  1. The Crawler is a Diva. It only runs on your live, production site. This means you can’t test search locally or on a staging branch. You have to push changes to production and wait. Debugging a misconfigured docsearch.json is an exercise in patience.
  2. You’re Locked In. Your search infrastructure is now a third-party service. If Algolia changes its pricing, has an outage, or decides to retire DocSearch, you’re in a tough spot. It’s not a portable solution.
  3. The “Free” Part. The free tier is incredibly generous, but it has limits. If your documentation site becomes wildly popular, you might hit them. Migrating off later would be a significant project.

So, should you use it? If you have a public documentation site and value a zero-maintenance, high-quality search experience over fine-grained control, absolutely. It’s a fantastic product. But if you need search to work in a CI environment, behind a login, or you just have a deep-seated aversion to relying on an external service, this is not your solution. You’d be better off with the build-time options we’ve discussed.