Document search-metadata frontmatter key for Algolia records

fern/products/docs/pages/customization/search.mdx

@@ -71,6 +71,60 @@ 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
+
+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 deploy-nim-on-kubernetes.mdx
+---
+title: Deploy NIM on Kubernetes with Helm
+search-metadata:
+  category: ai_and_machine_learning
+  audience: [developer, devops_engineer]
+  discovery:
+    technology_tags: [Kubernetes, Helm]
+---
+```
+
+Each of that page's records then carries:
+
+```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
+});
+```
+
+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.
+
+<Accordion title="Value types and limits">
+`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.
+</Accordion>
+
+Custom metadata is indexed for Markdown pages only. API reference and changelog records don't carry it.
+
 ## 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.

fern/products/docs/pages/navigation/frontmatter.mdx

@@ -358,6 +358,25 @@ nofollow: false
 </Accordion>
 </AccordionGroup>
 
+## Search metadata
+
+<ParamField path="search-metadata" type="object" required={false}>
+  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.
+</ParamField>
+
+<CodeBlock title="deploy-nim-on-kubernetes.mdx">
+```mdx
+---
+title: Deploy NIM on Kubernetes with Helm
+search-metadata:
+  category: ai_and_machine_learning
+  audience: [developer, devops_engineer]
+  discovery:
+    technology_tags: [Kubernetes, Helm]
+---
+```
+</CodeBlock>
+
 ## Availability
 
 <ParamField path="availability" type="string" required={false}>