From 582e049c493b0cd4a84f52d709c62b3ec73952bb Mon Sep 17 00:00:00 2001 From: Devin Date: Mon, 31 Aug 2026 18:25:49 +0000 Subject: [PATCH 1/2] Document search-metadata frontmatter key --- .../docs/pages/customization/search.mdx | 27 +++++++++++++++++++ .../docs/pages/navigation/frontmatter.mdx | 18 +++++++++++++ 2 files changed, 45 insertions(+) diff --git a/fern/products/docs/pages/customization/search.mdx b/fern/products/docs/pages/customization/search.mdx index 9f01890b9d..8cdb493256 100644 --- a/fern/products/docs/pages/customization/search.mdx +++ b/fern/products/docs/pages/customization/search.mdx @@ -71,6 +71,33 @@ experimental: 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. +### Custom search metadata + +Fern reads the `search-metadata` key from a page's frontmatter and merges those key-value pairs into the page's Algolia record. Use it to attach your own taxonomy (product line, audience, category) to pages and build a faceted search experience around it: + +```mdx +--- +title: CUDA Programming Guide +search-metadata: + product: CUDA + audience: developer + category: programming-guide +--- +``` + +The value must be a YAML mapping of string keys to string or array-of-string values. Array values cover multi-value facets, such as a page that belongs to two product lines: + +```mdx +--- +title: cuDNN Developer Guide +search-metadata: + product: [cuDNN, CUDA] + audience: developer +--- +``` + +Custom metadata fields are stored on the Algolia record, but Fern's built-in search filters don't use them. Surfacing them as filters requires configuring the fields as facets in Algolia and building or extending a search UI with your [Algolia credentials](#integrating-with-algolia). Pages without a `search-metadata` key are unaffected. + ## 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. diff --git a/fern/products/docs/pages/navigation/frontmatter.mdx b/fern/products/docs/pages/navigation/frontmatter.mdx index d46d355fa5..f2f45d1ca7 100644 --- a/fern/products/docs/pages/navigation/frontmatter.mdx +++ b/fern/products/docs/pages/navigation/frontmatter.mdx @@ -358,6 +358,24 @@ nofollow: false +## Search metadata + + + Custom key-value pairs merged into the page's Algolia search record. Keys are strings; values are strings or arrays of strings. Fern's built-in search filters ignore these fields, so surfacing them requires [configuring facets in Algolia and building your own search UI](/learn/docs/customization/search#custom-search-metadata). + + + +```mdx +--- +title: CUDA Programming Guide +search-metadata: + product: CUDA + audience: developer + category: programming-guide +--- +``` + + ## Availability From 90799a5a6c4dc5bbb5777805d34715727742cb6a Mon Sep 17 00:00:00 2001 From: Devin Date: Mon, 31 Aug 2026 18:33:57 +0000 Subject: [PATCH 2/2] Document search-metadata frontmatter key --- .../docs/pages/customization/search.mdx | 57 ++++++++++++++----- .../docs/pages/navigation/frontmatter.mdx | 13 +++-- 2 files changed, 49 insertions(+), 21 deletions(-) diff --git a/fern/products/docs/pages/customization/search.mdx b/fern/products/docs/pages/customization/search.mdx index 8cdb493256..4dbabeff66 100644 --- a/fern/products/docs/pages/customization/search.mdx +++ b/fern/products/docs/pages/customization/search.mdx @@ -73,30 +73,57 @@ Each entry points to a `sitemap.xml` or a sitemap index; nested indexes are expa ### Custom search metadata -Fern reads the `search-metadata` key from a page's frontmatter and merges those key-value pairs into the page's Algolia record. Use it to attach your own taxonomy (product line, audience, category) to pages and build a faceted search experience around it: +The `search-metadata` frontmatter key attaches your own taxonomy to a page: product line, audience, content type, or any other dimension your readers browse by. Fern copies the block onto every Algolia record generated from that page, under the `search_metadata` attribute, and declares it for faceting, so no per-site Algolia configuration is required. -```mdx +```mdx deploy-nim-on-kubernetes.mdx --- -title: CUDA Programming Guide +title: Deploy NIM on Kubernetes with Helm search-metadata: - product: CUDA - audience: developer - category: programming-guide + category: ai_and_machine_learning + audience: [developer, devops_engineer] + discovery: + technology_tags: [Kubernetes, Helm] --- ``` -The value must be a YAML mapping of string keys to string or array-of-string values. Array values cover multi-value facets, such as a page that belongs to two product lines: +Each of that page's records then carries: -```mdx ---- -title: cuDNN Developer Guide -search-metadata: - product: [cuDNN, CUDA] - audience: developer ---- +```json +"search_metadata": { + "category": "ai_and_machine_learning", + "audience": ["developer", "devops_engineer"], + "discovery": { "technology_tags": ["Kubernetes", "Helm"] } +} +``` + +Query the fields by their full path, using the [Algolia credentials](#integrating-with-algolia) for your index: + +```js +index.search("", { + facets: ["search_metadata.category", "search_metadata.discovery.technology_tags"], + facetFilters: [["search_metadata.audience:developer"]], + distinct: true +}); ``` -Custom metadata fields are stored on the Algolia record, but Fern's built-in search filters don't use them. Surfacing them as filters requires configuring the fields as facets in Algolia and building or extending a search UI with your [Algolia credentials](#integrating-with-algolia). Pages without a `search-metadata` key are unaffected. +Facet counts are computed after deduplication, so each page counts once rather than once per heading section. Facets are searchable, which supports high-cardinality dimensions like technology tags. + +Fern doesn't interpret the values. They don't affect ranking, and they don't appear in Fern's built-in filter dropdowns, which cover a fixed set of attributes. Surfacing custom metadata as filters requires building or extending a search UI on top of the index. Pages without a `search-metadata` key are unaffected. + + +`search-metadata` accepts a YAML mapping. Values can be strings, numbers, booleans, arrays, or nested mappings; dates are indexed as ISO 8601 strings. Fern normalizes the block before indexing: + +| Rule | Behavior | +| --- | --- | +| Keys containing `:` or `.` | Dropped, since both are delimiters in Algolia's filter syntax | +| Empty strings and empty arrays | Dropped | +| Nesting deeper than 5 levels | Subtrees below that depth are dropped | +| Blocks over 4 KB serialized | The entire block is dropped for that page, and a warning is logged during indexing | + +The block is duplicated onto every record of a page, so keep it to the dimensions you actually facet on. + + +Custom metadata is indexed for Markdown pages only. API reference and changelog records don't carry it. ## How results are ranked diff --git a/fern/products/docs/pages/navigation/frontmatter.mdx b/fern/products/docs/pages/navigation/frontmatter.mdx index f2f45d1ca7..65315b7647 100644 --- a/fern/products/docs/pages/navigation/frontmatter.mdx +++ b/fern/products/docs/pages/navigation/frontmatter.mdx @@ -361,17 +361,18 @@ nofollow: false ## Search metadata - Custom key-value pairs merged into the page's Algolia search record. Keys are strings; values are strings or arrays of strings. Fern's built-in search filters ignore these fields, so surfacing them requires [configuring facets in Algolia and building your own search UI](/learn/docs/customization/search#custom-search-metadata). + Author-defined metadata copied onto the page's Algolia search records under `search_metadata`, where it can be faceted and filtered on by full path. Values can be strings, numbers, booleans, arrays, or nested mappings. Fern doesn't interpret the values, and they don't appear in the built-in search filters. See [custom search metadata](/learn/docs/customization/search#custom-search-metadata) for the querying details and the depth and size limits. - + ```mdx --- -title: CUDA Programming Guide +title: Deploy NIM on Kubernetes with Helm search-metadata: - product: CUDA - audience: developer - category: programming-guide + category: ai_and_machine_learning + audience: [developer, devops_engineer] + discovery: + technology_tags: [Kubernetes, Helm] --- ```