> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. # Search configuration > Configure search for your Fern docs using Algolia DocSearch. Learn how search filters work, how results are ranked, and how to integrate with Algolia. Fern uses [Algolia DocSearch](https://docsearch.algolia.com/) 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](/learn/docs/configuration/products)) * **Version:** Filters results by documentation version (for sites using [versioned docs](/learn/docs/configuration/versions)) * **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 Pages with the `nofollow` or `noindex` [frontmatter](/learn/docs/configuration/page-level-settings#indexing-properties) are excluded from the Algolia DocSearch index and won't appear in search results. For sites with [localized docs](/learn/docs/localization/overview), search is automatically scoped to the reader's active language. For [multi-source sites](/learn/docs/preview-publish/multi-source-docs), search scope across sub-paths (hierarchical vs. unified) is configured per-domain in the [Fern Dashboard](https://dashboard.buildwithfern.com). If you're using [Ask Fern](/learn/docs/ai-features/ask-fern/overview) (AI search), the search box also functions as your site's chat window. ### Scope search by product or version For sites with multiple [products](/learn/docs/configuration/products) or [versions](/learn/docs/configuration/versions), the `settings.search` object in `docs.yml` scopes search results to the reader's current context (their active product and version). Two options are available: * [`prioritize-current-product`](/learn/docs/configuration/site-level-settings#settingssearchprioritize-current-product) — *Softer*. Boosts current-context results in ranking but still surfaces matches from other products and versions. * [`default-filter-by-current-product`](/learn/docs/configuration/site-level-settings#settingssearchdefault-filter-by-current-product) — *Stricter*. Hides results outside the current context by default; users can remove the filter from the search UI to broaden their search. Most sites pick one. For example, to boost current-context results without hiding anything else: **`docs.yml`** ```yaml docs.yml settings: search: prioritize-current-product: true ``` These settings apply to keyword search only. [Ask Fern](/learn/docs/ai-features/ask-fern/overview) queries the same Algolia index and benefits from its global ranking, but doesn't receive the per-product boost from `prioritize-current-product`. ### Index external sitemaps Fern can index pages hosted outside your docs site so they appear in search alongside your documentation. List one or more external sitemaps under the [`experimental.external-sitemaps` key](/learn/docs/configuration/site-level-settings#experimental-configuration) in `docs.yml`: **`docs.yml`** ```yaml docs.yml experimental: external-sitemaps: - https://example.com/sitemap.xml - https://example.com/sitemap-index.xml ``` Each entry points to a `sitemap.xml` or a sitemap index; nested indexes are expanded automatically. Fern fetches every listed sitemap, indexes its URLs into the same Algolia index as your documentation, and tags them to your docs domain. External results are flagged as third-party, which demotes them below all first-party pages in the ranking, and they open in a new tab when selected. ## 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](/learn/docs/configuration/page-level-settings#document-properties) set in the page's frontmatter. Use these to surface a page for queries without changing its content. | | 2 | Page title | The [title](/learn/docs/configuration/page-level-settings#title) set in frontmatter or `docs.yml` | | 3 | Heading hierarchy (h1–h6) | [Headings](/learn/docs/writing-content/markdown-basics#page-header) 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](/learn/docs/configuration/page-level-settings#meta-description) | | 10 | Body content | The full body text of the page | | 11 | Code snippets | [Code blocks](/learn/docs/writing-content/components/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: 1. **Date (descending):** Newer content ranks higher. This primarily affects changelog entries, which carry a timestamp. 2. **Version index (ascending):** Content from the default version ranks above content from older versions. This prevents duplicate results across versioned docs. 3. **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 use the [standalone widgets](/learn/docs/ai-features/search-widget/overview) to embed a ready-made React search or chat component, or request Algolia credentials directly from the Fern team to build a custom integration. ### 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. ### Facet on custom page metadata Keys nested under the `search-metadata` frontmatter object are copied onto every Algolia record for that page and declared for faceting, so a custom integration can group and filter results by your own taxonomy: #### plant-care.mdx ```mdx --- title: Watering your monstera search-metadata: category: plant_care audience: [gardener, botanist] discovery: technology_tags: [humidity, drainage] --- ``` Fern stores the block under the record's `search_metadata` attribute and facets each key by its full path: ```js index.search("", { facets: ["search_metadata.category", "search_metadata.discovery.technology_tags"], facetFilters: [["search_metadata.audience:gardener"]], distinct: true, }); ``` Values can be strings, numbers, booleans, dates, arrays, or nested objects; dates are indexed as ISO 8601 strings. Keys containing `:` or `.` are dropped, because those characters delimit Algolia's filter syntax. Fern also drops subtrees nested more than five levels deep, and drops a page's block entirely if it serializes to more than 4,000 bytes (the block is duplicated onto every section record of a page). Only markdown pages carry these attributes; API Reference and changelog records don't. Custom attributes are queryable through the Algolia API only, and don't appear in Fern's built-in search filters. ## Using an alternative search You can override Fern's search with your own solution using [custom JavaScript](/learn/docs/building-and-customizing-your-docs/custom-css-global-js#custom-javascript) and your Algolia credentials. ## Disable search When you're replacing Fern's search with your own solution, set [`disable-search`](/learn/docs/configuration/site-level-settings#settingsdisable-search) to `true` to remove the default search bar from your site: **`docs.yml`** ```yaml docs.yml settings: disable-search: true ``` To keep search working but exclude specific content from results, use [`hidden` and `noindex`](/learn/docs/customization/hiding-content) instead. > Configure search for your Fern docs using Algolia DocSearch. Learn how search filters work, how results are ranked, and how to integrate with Algolia.