fern-api · devalog · Aug 25, 2025 · Aug 23, 2025
diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml
@@ -170,6 +170,8 @@ navigation:
     slug: seo
     collapsed: true
     contents:
+      - page: Setting SEO metadata
+        path: ./pages/seo/metadata.mdx
       - page: Configuring slugs
         path: ./pages/seo/configuring-slugs.mdx
       - page: Redirects

diff --git a/fern/products/docs/pages/customization/frontmatter.mdx b/fern/products/docs/pages/customization/frontmatter.mdx
@@ -245,120 +245,8 @@ Currently, relative paths are _not_ supported for this field.
 
 ## SEO metadata
 
-<Note title="SEO Best Practices">
-Looking to set metadata across the entire site? [Use the metadata field in the `docs.yml` file](/learn/docs/configuration/what-is-docs-yml#metadata-configuration).
-
-When configuring SEO metadata, ensure your titles and descriptions are unique, descriptive, and relevant to the page content. Keep descriptions between 150-160 characters for optimal display in search results.
+<Note title="Looking to set metadata across the entire site?">
+ [Use the metadata field in the `docs.yml` file](/learn/docs/configuration/what-is-docs-yml#seo-metadata-configuration).
 </Note>
 
-<CodeBlock title="Example SEO metadata">
-```mdx
----
-title: PlantStore API Quick Start
-headline: "Get Started with PlantStore API | Developer Documentation"
-keywords: plants, garden, nursery
-canonical-url: https://docs.plantstore.dev/welcome
-og:site_name: PlantStore Developer Documentation
-og:title: "PlantStore API Quick Start Guide"
-og:description: "Learn how to integrate with PlantStore's API to manage plant inventory, process orders, and track shipments. Complete with code examples."
-og:image: https://plantstore.dev/images/api-docs-banner.png
-og:image:width: 1200
-og:image:height: 630
-twitter:card: summary_large_image
-twitter:site: "@PlantStoreAPI"
-noindex: false
-nofollow: false
----
-```
-</CodeBlock>
-
-### Document Properties
-<ParamField path="headline" type="string" required={false}>
-  When set, the `<title />` tag in the document head will use this value rather than the `title` property. This property changes the title that search engines see when crawling this page, and can be used to address Duplicate Title issues in your SEO report.
-</ParamField>
-
-<ParamField path="canonical-url" type="string" required={false}>
-  Overrides the canonical URL for this page. Must be a full URL including the protocol (i.e. `https://buildwithfern.com/learn/docs/content/frontmatter`)
-</ParamField>
-
-<ParamField path="keywords" type="string" required={false}>
-  Comma-separated string of keywords relevant to the page content (i.e. `plants, garden, nursery`). These keywords help search engines understand the page topic and contributes to search rankings. Use specific, relevant terms that users might search for when looking for the page's content.
-
-  This field accepts only comma-separated strings, not bracketed arrays.
-
-</ParamField>
-
-### OpenGraph Properties
-<ParamField path="og:site_name" type="string" required={false}>
-  The name of your website as it should appear when your content is shared.
-</ParamField>
-
-<ParamField path="og:title" type="string" required={false}>
-  The title of your page as it should appear when your content is shared.
-</ParamField>
-
-<ParamField path="og:description" type="string" required={false}>
-  The description of your page as it should appear when your content is shared.
-</ParamField>
-
-<ParamField path="og:url" type="string" required={false}>
-  The URL of your page.
-</ParamField>
-
-<ParamField path="og:image" type="string" required={false}>
-  The URL or identifier of the image that will be displayed when your content is shared.
-</ParamField>
-
-<ParamField path="og:image:width" type="number" required={false}>
-  The width of the image in pixels.
-</ParamField>
-
-<ParamField path="og:image:height" type="number" required={false}>
-  The height of the image in pixels.
-</ParamField>
-
-<ParamField path="og:locale" type="string" required={false}>
-  The locale of the page, typically in the format `language_TERRITORY` (e.g., `en_US`).
-</ParamField>
-
-<ParamField path="og:logo" type="string" required={false}>
-  The URL or identifier of the logo image of your website that will be displayed when your content is shared.
-</ParamField>
-
-### Twitter Properties
-<ParamField path="twitter:title" type="string" required={false}>
-  The title of your page as it should appear in a tweet.
-</ParamField>
-
-<ParamField path="twitter:description" type="string" required={false}>
-  The description of your page as it should appear in a tweet.
-</ParamField>
-
-<ParamField path="twitter:handle" type="string" required={false}>
-  The Twitter handle of the page creator or site.
-</ParamField>
-
-<ParamField path="twitter:image" type="string" required={false}>
-  The URL or identifier of the image that will be displayed in a tweet.
-</ParamField>
-
-<ParamField path="twitter:site" type="string" required={false}>
-  The name of your website as it should appear in a tweet.
-</ParamField>
-
-<ParamField path="twitter:url" type="string" required={false}>
-  The URL of your page.
-</ParamField>
-
-<ParamField path="twitter:card" type="string" required={false}>
-  The type of card to be used for sharing on Twitter. Options: `summary`, `summary_large_image`, `app`, `player`
-</ParamField>
-
-### Indexing Properties
-<ParamField path="noindex" type="boolean" required={false} default={false}>
-  If set to `true`, the page will not be indexed by search engines.
-</ParamField>
-
-<ParamField path="nofollow" type="boolean" required={false} default={false}>
-  If set to `true`, a search engine will not follow any links present on the page.
-</ParamField>
+<Markdown src="/snippets/seo-metadata-page.mdx" />
diff --git a/fern/products/docs/pages/customization/what-is-docs-yml.mdx b/fern/products/docs/pages/customization/what-is-docs-yml.mdx
@@ -100,7 +100,7 @@ navbar-links:
 
 <ParamField path="metadata" type="object" required={false}>
   Configure SEO metadata for your documentation website. Learn more about the 
-  [`metadata` configuration](/learn/docs/getting-started/global-configuration#metadata-configuration).
+  [`metadata` configuration](/learn/docs/getting-started/global-configuration#seo-metadata-configuration).
 </ParamField>
 
 ## Instances configuration
@@ -523,91 +523,13 @@ landing-page:
 
 See [Vapi's landing page live](https://docs.vapi.ai/) and the associated [Markdown file](https://github.com/VapiAI/docs/blob/main/fern/quickstart/introduction.mdx?plain=1).
 
-## Metadata configuration
+## SEO metadata configuration
 
-```yaml docs.yml
-metadata:
-  # Core platform identity
-  og:site_name: "Square Developer Documentation"
-  og:title: "Square Developer Platform | Payments, Commerce & Banking APIs"
-  og:description: "Build with Square's suite of APIs and SDKs. Accept payments, manage inventory, create loyalty programs, and access financial services. Complete documentation for developers building the future of commerce."
-  og:url: "https://developer.squareup.com/docs"
-
-  # Social sharing assets
-  og:image: "https://developer.squareup.com/images/docs-social-card.png"
-  og:image:width: 1200
-  og:image:height: 630
-  og:locale: "en_US"
-  og:logo: "https://developer.squareup.com/images/square-logo.png"
-
-  # Twitter (I mean X) optimization
-  twitter:title: "Square Developer Platform Documentation"
-  twitter:description: "Integrate payments, point-of-sale, inventory, and financial services into your applications with Square's developer platform. Get started with our APIs, SDKs, and comprehensive guides."
-  twitter:handle: "@SquareDev"
-  twitter:image: "https://developer.squareup.com/images/twitter-card.png"
-  twitter:site: "@Square"
-  twitter:card: "summary_large_image"
-```
-
-<ParamField path="metadata.og:site_name" type="string" required={false}>
-  The name of your website for Open Graph tags.
-</ParamField>
-
-<ParamField path="metadata.og:title" type="string" required={false}>
-  The title shown in social media previews.
-</ParamField>
-
-<ParamField path="metadata.og:description" type="string" required={false}>
-  The description shown in social media previews.
-</ParamField>
-
-<ParamField path="metadata.og:url" type="string" required={false}>
-  The canonical URL of your documentation.
-</ParamField>
-
-<ParamField path="metadata.og:image" type="string" required={false}>
-  The image shown in social media previews. Recommended size is 1200x630 pixels.
-</ParamField>
-
-<ParamField path="metadata.og:image:width" type="number" required={false}>
-  The width of your Open Graph image in pixels.
-</ParamField>
-
-<ParamField path="metadata.og:image:height" type="number" required={false}>
-  The height of your Open Graph image in pixels.
-</ParamField>
+<Note title="Looking to set metadata for a single page?">
+ [Use the `keywords` property in a page's frontmatter](/docs/configuration/page-level-settings#seo-metadata).
+</Note>
 
-<ParamField path="metadata.og:locale" type="string" required={false}>
-  The locale of your content (e.g., "en_US").
-</ParamField>
-
-<ParamField path="metadata.og:logo" type="string" required={false}>
-  URL to your company logo.
-</ParamField>
-
-<ParamField path="metadata.twitter:title" type="string" required={false}>
-  The title shown in Twitter Card previews.
-</ParamField>
-
-<ParamField path="metadata.twitter:description" type="string" required={false}>
-  The description shown in Twitter Card previews.
-</ParamField>
-
-<ParamField path="metadata.twitter:handle" type="string" required={false}>
-  Your company's Twitter handle.
-</ParamField>
-
-<ParamField path="metadata.twitter:image" type="string" required={false}>
-  The image shown in Twitter Card previews.
-</ParamField>
-
-<ParamField path="metadata.twitter:site" type="string" required={false}>
-  The Twitter handle for your website.
-</ParamField>
-
-<ParamField path="metadata.twitter:card" type="string" required={false}>
-  The Twitter Card type. Options are `summary`, `summary_large_image`, `app`, or `player`.
-</ParamField>
+<Markdown src="/snippets/seo-metadata-site.mdx" />
 
 ## Analytics configuration
 

diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx
@@ -0,0 +1,20 @@
+---
+title: Configure SEO metadata
+description: Configure SEO metadata at the page or site level.  
+---
+
+Optimize your documentation's search visibility and social media presence by configuring SEO metadata at the page or site level. Properly configured metadata helps search engines understand your content and creates compelling previews when your pages are shared on social platforms.
+
+When configuring SEO metadata, ensure your titles and descriptions are unique, descriptive, and relevant to the page content. Keep descriptions between 150-160 characters for optimal display in search results.
+
+## Page metadata
+
+Set SEO properties in each page's [frontmatter](/docs/configuration/page-level-settings) to control how individual pages appear in search results and social media shares. Page-level metadata takes precedence over site-wide settings.
+
+<Markdown src="/snippets/seo-metadata-page.mdx" />
+
+## Website metadata
+
+Define default SEO properties for your entire documentation site in your [`docs.yml` file](/docs/configuration/what-is-docs-yml). These settings apply to all pages unless overridden by page-specific metadata.
+
+<Markdown src="/snippets/seo-metadata-site.mdx" />
diff --git a/fern/snippets/seo-metadata-page.mdx b/fern/snippets/seo-metadata-page.mdx
@@ -0,0 +1,118 @@
+<CodeBlock title="plantstore-quickstart.mdx">
+```mdx
+---
+title: PlantStore API Quick Start
+headline: "Get Started with PlantStore API | Developer Documentation"
+keywords: plants, garden, nursery
+canonical-url: https://docs.plantstore.dev/welcome
+og:site_name: PlantStore Developer Documentation
+og:title: "PlantStore API Quick Start Guide"
+og:description: "Learn how to integrate with PlantStore's API to manage plant inventory, process orders, and track shipments. Complete with code examples."
+og:image: https://plantstore.dev/images/api-docs-banner.png
+og:image:width: 1200
+og:image:height: 630
+twitter:card: summary_large_image
+twitter:site: "@PlantStoreAPI"
+noindex: false
+nofollow: false
+---
+```
+</CodeBlock>
+
+<AccordionGroup>
+<Accordion title="Document properties">
+
+<ParamField path="headline" type="string" required={false}>
+  When set, the `<title />` tag in the document head will use this value rather than the `title` property. This property changes the title that search engines see when crawling this page, and can be used to address Duplicate Title issues in your SEO report.
+</ParamField>
+
+<ParamField path="canonical-url" type="string" required={false}>
+  Overrides the canonical URL for this page. Must be a full URL including the protocol (i.e. `https://buildwithfern.com/learn/docs/content/frontmatter`)
+</ParamField>
+
+<ParamField path="keywords" type="string" required={false}>
+  Comma-separated string of keywords relevant to the page content (i.e. `plants, garden, nursery`). These keywords help search engines understand the page topic and contributes to search rankings. Use specific, relevant terms that users might search for when looking for the page's content.
+
+  This field accepts only comma-separated strings, not bracketed arrays.
+
+</ParamField>
+
+</Accordion>
+<Accordion title="OpenGraph properties">
+
+<ParamField path="og:site_name" type="string" required={false}>
+  The name of your website as it should appear when your content is shared.
+</ParamField>
+
+<ParamField path="og:title" type="string" required={false}>
+  The title of your page as it should appear when your content is shared.
+</ParamField>
+
+<ParamField path="og:description" type="string" required={false}>
+  The description of your page as it should appear when your content is shared.
+</ParamField>
+
+<ParamField path="og:url" type="string" required={false}>
+  The URL of your page.
+</ParamField>
+
+<ParamField path="og:image" type="string" required={false}>
+  The URL or identifier of the image that will be displayed when your content is shared.
+</ParamField>
+
+<ParamField path="og:image:width" type="number" required={false}>
+  The width of the image in pixels.
+</ParamField>
+
+<ParamField path="og:image:height" type="number" required={false}>
+  The height of the image in pixels.
+</ParamField>
+
+<ParamField path="og:locale" type="string" required={false}>
+  The locale of the page, typically in the format `language_TERRITORY` (e.g., `en_US`).
+</ParamField>
+
+<ParamField path="og:logo" type="string" required={false}>
+  The URL or identifier of the logo image of your website that will be displayed when your content is shared.
+</ParamField>
+</Accordion>
+<Accordion title="Twitter properties">
+
+<ParamField path="twitter:title" type="string" required={false}>
+  The title of your page as it should appear in a tweet.
+</ParamField>
+
+<ParamField path="twitter:description" type="string" required={false}>
+  The description of your page as it should appear in a tweet.
+</ParamField>
+
+<ParamField path="twitter:handle" type="string" required={false}>
+  The Twitter handle of the page creator or site.
+</ParamField>
+
+<ParamField path="twitter:image" type="string" required={false}>
+  The URL or identifier of the image that will be displayed in a tweet.
+</ParamField>
+
+<ParamField path="twitter:site" type="string" required={false}>
+  The name of your website as it should appear in a tweet.
+</ParamField>
+
+<ParamField path="twitter:url" type="string" required={false}>
+  The URL of your page.
+</ParamField>
+
+<ParamField path="twitter:card" type="string" required={false}>
+  The type of card to be used for sharing on Twitter. Options: `summary`, `summary_large_image`, `app`, `player`
+</ParamField>
+</Accordion>
+<Accordion title="Indexing properties">
+<ParamField path="noindex" type="boolean" required={false} default={false}>
+  If set to `true`, the page will not be indexed by search engines.
+</ParamField>
+
+<ParamField path="nofollow" type="boolean" required={false} default={false}>
+  If set to `true`, a search engine will not follow any links present on the page.
+</ParamField>
+</Accordion>
+</AccordionGroup>