Search configuration | Fern Documentation

Fern uses Algolia DocSearch to power search for your documentation. DocSearch is designed specifically for documentation sites to help users find what they need.

How search works

DocSearch scans your Fern site’s content and builds an index to generate search results. It includes built-in dropdown filters that appear dynamically based on your site’s configuration, letting users refine their searches:

Product: Narrows results to a specific product in your documentation (for sites with multiple products)
Version: Filters results by documentation version (for sites using versioned docs)
Content type: Filters results by guides, changelog entries, or API endpoints
API type: Filters API results by protocol (HTTP, webhooks, WebSockets, or gRPC)
HTTP method: Filters API results by HTTP method (GET, POST, PUT, DELETE, etc.)
Status code: Filters API results by HTTP status code
Availability: Filters API results by availability status, including Stable, Beta, and Deprecated

Fern's own docs site shows Product, Content type, and HTTP method filters. Other filters, like Version, don't appear because this site doesn't use versioned docs.

For sites with multiple products or versions, you can scope search results to the user’s current product and version by default. Set default-search-filters: true in your docs.yml settings to enable this. Users can still remove these filters to broaden their search.

If you’re using Ask Fern (AI search), the search box also functions as your site’s chat window.

Pages with the nofollow or noindex frontmatter are excluded from the Algolia DocSearch index and won’t appear in search results.

How results are ranked

Fern configures Algolia’s ranking to prioritize matches in high-signal attributes like titles and keywords over body text, then applies tiebreakers for recency, version, and page position.

Attribute weighting

Algolia ranks results based on which attributes contain the matching text. Attributes listed earlier are weighted higher than those listed later. Fern configures the following searchable attributes, in order of priority:

Priority	Attribute	Description
1	Keywords	Keywords set in the page’s frontmatter. Use these to surface a page for queries without changing its content.
2	Page title	The title set in frontmatter or `docs.yml`
3	Heading hierarchy (h1–h6)	Headings within the page, from h1 (highest) to h6 (lowest)
4	Endpoint path	The API endpoint path (e.g., `/plants/{plantId}`)
5	Endpoint path alternates	Alternative representations of the endpoint path
6	Parameter name	Names of API parameters
7	Metadata attributes	Availability, API type, HTTP method, content type, response type, status code, and parameter type
8	Breadcrumb	The navigation breadcrumb trail for the page
9	Description	The page’s meta description
10	Body content	The full body text of the page
11	Code snippets	Code blocks embedded in the page

All attributes use unordered matching, meaning that the position of the query terms within an attribute doesn’t affect ranking. For example, a match at the end of a page title ranks the same as a match at the beginning.

Tiebreaking

When multiple results have the same text relevance score, Fern applies custom ranking rules as tiebreakers:

Date (descending): Newer content ranks higher. This primarily affects changelog entries, which carry a timestamp.
Version index (ascending): Content from the default version ranks above content from older versions. This prevents duplicate results across versioned docs.
Page position (ascending): Content closer to the top of a page ranks above content further down. For example, a heading match near the top of a page outranks a section match further down on the same page.

Additionally, Fern deduplicates results by canonical pathname, so each page appears at most once in the results. The version index and page position tiebreakers determine which record represents the page when duplicates exist.

Page hierarchy

The navigation hierarchy of your documentation doesn’t directly affect search ranking. A nested page ranks the same as a top-level page for text relevance purposes. However, within a single page, heading depth does matter: matches in h1 headings rank above h2, h2 above h3, and so on. The heading hierarchy is stored per record, so Algolia can distinguish between a match in a top-level section and one in a subsection.

Empty result handling

If a query returns no results, Algolia progressively removes common documentation terms to broaden the search. The following words are treated as optional when no exact matches are found: endpoint, api, guide, documentation, doc, parameter, webhook, websocket, http, code, and snippet.

For example, a search for webhook endpoint that returns no results is retried as webhook and endpoint individually.

Integrating with Algolia

If you need to integrate Fern’s documentation search into your own application or dashboard, you can request Algolia credentials directly from the Fern team. These credentials will allow you to query the same search index that powers your documentation site’s search functionality.

Making search requests

Once you have your credentials, you can make requests to Algolia’s API to search your documentation.

Contact the Fern team to get your specific application ID and index name. Credentials are provided on a per-customer basis to maintain security.

Note: Keep your Algolia credentials secure and avoid exposing them in client-side code. Consider implementing a backend proxy to make the Algolia requests.

Using an alternative search

You can override Fern’s search with your own solution using custom JavaScript and your Algolia credentials.