Document redesigned dynamic OG images with toggle flags and color overrides

fern/products/docs/pages/changelog/2026-03-17.mdx

@@ -0,0 +1,27 @@
+---
+tags: ["seo", "configuration", "docs.yml"]
+---
+
+## Redesigned dynamic OG images <Availability type="beta" /> [#og-image-redesign]
+
+Dynamic OG images have a new layout with more content and fine-grained control:
+
+- **Section title** derived from the page's navigation breadcrumb, styled with your accent color
+- **Page description** extracted from frontmatter, clamped to two lines
+- **Page URL** displayed below the description
+- **Dark mode default** with a subtle accent gradient overlay
+- **Toggle flags** to show or hide individual elements (logo, section, description, URL, gradient)
+
+```yaml docs.yml
+metadata:
+  og:dynamic: true
+  og:dynamic:text-color: "#1a1a1a"
+  og:dynamic:background-color: "#ffffff"
+  og:dynamic:show-logo: true
+  og:dynamic:show-section: true
+  og:dynamic:show-description: true
+  og:dynamic:show-url: true
+  og:dynamic:show-gradient: true
+```
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/seo/setting-seo-metadata#dynamic-og-images">Read the docs</Button>

fern/products/docs/pages/seo/metadata.mdx

@@ -114,6 +114,13 @@ You can optionally provide a custom background image (`og:background-image`) for
 metadata:
   og:dynamic: true
   og:background-image: ./images/og-background.png # optional
+  og:dynamic:text-color: "#1a1a1a" # optional
+  og:dynamic:background-color: "#ffffff" # optional
+  og:dynamic:show-logo: true # optional
+  og:dynamic:show-section: true # optional
+  og:dynamic:show-description: true # optional
+  og:dynamic:show-url: true # optional
+  og:dynamic:show-gradient: true # optional
 ```
 
 <ParamField path="metadata.og:dynamic" type="boolean" required={false} default={false} toc={true}>
@@ -124,6 +131,34 @@ metadata:
   A custom background image for dynamically generated OG images. Can be a URL or a relative file path. When set, this image is used as the background instead of a solid color.
 </ParamField>
 
+<ParamField path="metadata.og:dynamic:text-color" type="string" required={false} toc={true}>
+  Override the text color for dynamically generated OG images. Accepts any valid CSS color value (e.g., `"#1a1a1a"`). By default, Fern auto-detects the text color from your site's theme. Use this when the auto-detected color doesn't contrast well with your background.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:background-color" type="string" required={false} toc={true}>
+  Override the background color for dynamically generated OG images. Accepts any valid CSS color value (e.g., `"#ffffff"`). By default, Fern uses your site's theme background color.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:show-logo" type="boolean" required={false} default={true} toc={true}>
+  Toggle visibility of the logo in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:show-section" type="boolean" required={false} default={true} toc={true}>
+  Toggle visibility of the section title in dynamically generated OG images. The section title is derived from the page's navigation breadcrumb. Defaults to `true` when `og:dynamic` is enabled.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:show-description" type="boolean" required={false} default={true} toc={true}>
+  Toggle visibility of the page description in dynamically generated OG images. The description is extracted from the page's frontmatter (`description`, `subtitle`, or `excerpt`). Defaults to `true` when `og:dynamic` is enabled.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:show-url" type="boolean" required={false} default={true} toc={true}>
+  Toggle visibility of the page URL in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:show-gradient" type="boolean" required={false} default={true} toc={true}>
+  Toggle visibility of the accent gradient overlay in dynamically generated OG images. The gradient uses your accent color. Defaults to `true` when `og:dynamic` is enabled.
+</ParamField>
+
 ### Twitter / X
 
 Controls how your docs appear in Twitter Card previews when shared on X.

fern/snippets/seo-metadata-site.mdx

@@ -17,6 +17,13 @@ metadata:
   # Dynamic OG images (beta)
   og:dynamic: true
   og:background-image: "https://developer.squareup.com/images/og-background.png"
+  og:dynamic:text-color: "#1a1a1a"
+  og:dynamic:background-color: "#ffffff"
+  og:dynamic:show-logo: true
+  og:dynamic:show-section: true
+  og:dynamic:show-description: true
+  og:dynamic:show-url: true
+  og:dynamic:show-gradient: true
 
   # Twitter/X
   twitter:title: "Square Developer Platform Documentation"
@@ -95,6 +102,34 @@ metadata:
   A custom background image for dynamically generated OG images. Can be a URL or a relative file path.
 </ParamField>
 
+<ParamField path="metadata.og:dynamic:text-color" type="string" required={false}>
+  Override the text color for dynamically generated OG images. Accepts any valid CSS color value. Use this when the auto-detected color doesn't contrast well with your background.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:background-color" type="string" required={false}>
+  Override the background color for dynamically generated OG images. Accepts any valid CSS color value.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:show-logo" type="boolean" required={false}>
+  Toggle visibility of the logo in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:show-section" type="boolean" required={false}>
+  Toggle visibility of the section title in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:show-description" type="boolean" required={false}>
+  Toggle visibility of the page description in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:show-url" type="boolean" required={false}>
+  Toggle visibility of the page URL in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled.
+</ParamField>
+
+<ParamField path="metadata.og:dynamic:show-gradient" type="boolean" required={false}>
+  Toggle visibility of the accent gradient overlay in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled.
+</ParamField>
+
 <ParamField path="metadata.canonical-host" type="string" required={false}>
   The host of your documentation website. This will be used to set the canonical URL for metadata tags and documents like the sitemap.