diff --git a/changelog.mdx b/changelog.mdx index 9f5b708cf..ee80bcfc7 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -96,7 +96,7 @@ noindex: true ## Section-level search boost - Search indexing now supports section-level boosts and page-level boosts, letting you promote specific content so it ranks higher for relevant queries. See the [search boost](/optimize/search-boost) documentation for more details. + Search indexing now supports section-level boosts and page-level boosts, letting you promote specific content so it ranks higher for relevant queries. See the [Search](/optimize/search#boost-search-ranking) documentation for more details. ## Improvements diff --git a/docs.json b/docs.json index ce483c4f1..10d6d0e33 100644 --- a/docs.json +++ b/docs.json @@ -233,7 +233,7 @@ "ai/llmstxt", "ai/skillmd", "ai/model-context-protocol", - "optimize/search-boost", + "optimize/search", "optimize/seo", "ai/markdown-export", "optimize/pdf-exports", diff --git a/images/search-settings-dark.png b/images/search-settings-dark.png new file mode 100644 index 000000000..21444c06a Binary files /dev/null and b/images/search-settings-dark.png differ diff --git a/images/search-settings-light.png b/images/search-settings-light.png new file mode 100644 index 000000000..34380a67d Binary files /dev/null and b/images/search-settings-light.png differ diff --git a/optimize/search-boost.mdx b/optimize/search-boost.mdx deleted file mode 100644 index e14b636cc..000000000 --- a/optimize/search-boost.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Search boost" -description: "Bias your in-product documentation search ranking toward specific pages or sections using the boost multiplier in frontmatter or in docs.json navigation." -keywords: ["search ranking", "search boost", "boost", "search prioritization"] ---- - -Use `boost` to bias the in-product search ranking of specific pages or sections. The value is a numeric multiplier applied to each chunk's relevance score: `boost: 3` makes a chunk three times as relevant as it would be without a boost. - -`boost` only affects the search bar on your Mintlify-hosted documentation site. It does not change how external search engines index your pages. - -## Boost a single page - -Set `boost` in a page's [frontmatter](/organize/pages) to multiply its search ranking. - -```mdx ---- -title: "Custom domain" -description: "Connect your custom domain to your Mintlify documentation." -boost: 3 ---- -``` - -## Boost a navigation group - -Set `boost` on a group in your `docs.json` navigation to apply the multiplier to every page under it. - -```json -{ - "navigation": { - "groups": [ - { - "group": "Get started", - "boost": 5, - "pages": [ - "quickstart", - "concepts" - ] - } - ] - } -} -``` - -A page inherits the boost factor from its nearest ancestor that sets one. A child page or nested group can override the inherited boost by setting its own `boost` value. A page's frontmatter `boost` always wins over a value inherited from the navigation. - -## De-prioritize content - -Use a value below `1` to push pages further down in search results. For example, `boost: 0.5` halves a page's relevance score relative to other pages. A `boost` of `1` is equivalent to no boost. - -```mdx ---- -title: "Deprecated API" -description: "Documentation for the deprecated v1 API." -boost: 0.25 ---- -``` - - - Boost factors compose with the existing relevance score. Use them sparingly. Large multipliers can cause less-relevant pages to dominate search results and degrade overall search quality. - diff --git a/optimize/search.mdx b/optimize/search.mdx new file mode 100644 index 000000000..93b2f7019 --- /dev/null +++ b/optimize/search.mdx @@ -0,0 +1,83 @@ +--- +title: "Search" +description: "Configure the in-product search bar on your Mintlify documentation site, including ranking boosts and the number of results returned per query." +keywords: ["search", "search ranking", "search boost", "boost", "search prioritization", "maximum search results", "max results"] +--- + +Configure how the search bar on your Mintlify-hosted documentation site behaves. These settings only affect in-product search. They do not change how external search engines index your pages. + +## Boost search ranking + +Use `boost` to bias the in-product search ranking of specific pages or sections. The value is a numeric multiplier applied to each chunk's relevance score: `boost: 3` makes a chunk three times as relevant as it would be without a boost. + +### Boost a single page + +Set `boost` in a page's [frontmatter](/organize/pages) to multiply its search ranking. + +```mdx +--- +title: "Custom domain" +description: "Connect your custom domain to your Mintlify documentation." +boost: 3 +--- +``` + +### Boost a navigation group + +Set `boost` on a group in your `docs.json` navigation to apply the multiplier to every page under it. + +```json +{ + "navigation": { + "groups": [ + { + "group": "Get started", + "boost": 5, + "pages": [ + "quickstart", + "concepts" + ] + } + ] + } +} +``` + +A page inherits the boost factor from its nearest ancestor that sets one. A child page or nested group can override the inherited boost by setting its own `boost` value. A page's frontmatter `boost` always wins over a value inherited from the navigation. + +### De-prioritize content + +Use a value below `1` to push pages further down in search results. For example, `boost: 0.5` halves a page's relevance score relative to other pages. A `boost` of `1` is equivalent to no boost. + +```mdx +--- +title: "Deprecated API" +description: "Documentation for the deprecated v1 API." +boost: 0.25 +--- +``` + + + Boost factors compose with the existing relevance score. Use them sparingly. Large multipliers can cause less-relevant pages to dominate search results and degrade overall search quality. + + +## Maximum search results + +Control how many results the search bar returns per query from your dashboard. The default is `6` results. You can set any value between `1` and `100`. + +In your dashboard, navigate to **Settings** > **Deployment** > **Search**, set **Maximum search results** to the value you want, and select **Save changes**. + + + The Search settings page in the dashboard with the Maximum search results stepper set to 6. + The Search settings page in the dashboard with the Maximum search results stepper set to 6. + + +Higher values surface more matches per query, which is useful for sites with broad topic coverage where users expect to scan many candidates. Lower values keep the results panel compact and push users toward the top-ranked match. diff --git a/organize/pages.mdx b/organize/pages.mdx index bb2e82909..f83b1493c 100644 --- a/organize/pages.mdx +++ b/organize/pages.mdx @@ -63,7 +63,7 @@ Use frontmatter to control: - Multiply the page's in-product search ranking by this factor. Use values greater than `1` to prioritize the page and values between `0` and `1` to de-prioritize it. See [Search boost](/optimize/search-boost) for details. + Multiply the page's in-product search ranking by this factor. Use values greater than `1` to prioritize the page and values between `0` and `1` to de-prioritize it. See [Search](/optimize/search#boost-search-ranking) for details. diff --git a/organize/settings-reference.mdx b/organize/settings-reference.mdx index 5791d9d81..36fa3b5bb 100644 --- a/organize/settings-reference.mdx +++ b/organize/settings-reference.mdx @@ -230,7 +230,7 @@ Groups for organizing content into labeled sections. ##### `navigation.groups[].boost` -Numeric multiplier applied to the in-product search ranking of every page in this group. Pages inherit the boost factor from the nearest ancestor group that sets one. Use values greater than `1` to prioritize, between `0` and `1` to de-prioritize. See [Search boost](/optimize/search-boost). +Numeric multiplier applied to the in-product search ranking of every page in this group. Pages inherit the boost factor from the nearest ancestor group that sets one. Use values greater than `1` to prioritize, between `0` and `1` to de-prioritize. See [Search](/optimize/search#boost-search-ranking). **Type:** number diff --git a/redirects.json b/redirects.json index 8da16788f..74ddca545 100644 --- a/redirects.json +++ b/redirects.json @@ -1,4 +1,8 @@ [ + { + "source": "/optimize/search-boost", + "destination": "/optimize/search" + }, { "source": "/ai/assistant", "destination": "/assistant/index"