From 7548309bc4b3606c8fa36862e4752e612c95f2de Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 17 Mar 2026 15:20:29 +0000 Subject: [PATCH 1/4] Add og:text-color and og:background-color documentation and changelog entry Co-Authored-By: Kapil Gowru --- .../products/docs/pages/changelog/2026-03-17.mdx | 16 ++++++++++++++++ fern/products/docs/pages/seo/metadata.mdx | 10 ++++++++++ fern/snippets/seo-metadata-site.mdx | 10 ++++++++++ 3 files changed, 36 insertions(+) create mode 100644 fern/products/docs/pages/changelog/2026-03-17.mdx diff --git a/fern/products/docs/pages/changelog/2026-03-17.mdx b/fern/products/docs/pages/changelog/2026-03-17.mdx new file mode 100644 index 000000000..514e4951a --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-03-17.mdx @@ -0,0 +1,16 @@ +--- +tags: ["seo", "configuration", "docs.yml"] +--- + +## Dynamic OG image color overrides [#og-color-overrides] + +You can now control the text and background colors of dynamically generated OG images. Set `og:text-color` and `og:background-color` in your `docs.yml` metadata to override the auto-detected theme colors. This is useful when your site has a light background where the default white text is hard to read. + +```yaml docs.yml +metadata: + og:dynamic: true + og:text-color: "#1a1a1a" + og:background-color: "#ffffff" +``` + + diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index fbac6cf22..81e110d3d 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -114,6 +114,8 @@ 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:text-color: "#1a1a1a" # optional + og:background-color: "#ffffff" # optional ``` @@ -124,6 +126,14 @@ 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. + + 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. + + + + 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. + + ### Twitter / X Controls how your docs appear in Twitter Card previews when shared on X. diff --git a/fern/snippets/seo-metadata-site.mdx b/fern/snippets/seo-metadata-site.mdx index 06b3684f1..157286095 100644 --- a/fern/snippets/seo-metadata-site.mdx +++ b/fern/snippets/seo-metadata-site.mdx @@ -17,6 +17,8 @@ metadata: # Dynamic OG images (beta) og:dynamic: true og:background-image: "https://developer.squareup.com/images/og-background.png" + og:text-color: "#1a1a1a" + og:background-color: "#ffffff" # Twitter/X twitter:title: "Square Developer Platform Documentation" @@ -95,6 +97,14 @@ metadata: A custom background image for dynamically generated OG images. Can be a URL or a relative file path. + + 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. + + + + Override the background color for dynamically generated OG images. Accepts any valid CSS color value. + + The host of your documentation website. This will be used to set the canonical URL for metadata tags and documents like the sitemap. From 9fee39deeeb5a18cce09685c412a0456d127dfff Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 17 Mar 2026 16:09:51 +0000 Subject: [PATCH 2/4] Rename og:text-color/og:background-color to og:dynamic:text-color/og:dynamic:background-color Co-Authored-By: Kapil Gowru --- fern/products/docs/pages/changelog/2026-03-17.mdx | 6 +++--- fern/products/docs/pages/seo/metadata.mdx | 8 ++++---- fern/snippets/seo-metadata-site.mdx | 8 ++++---- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/fern/products/docs/pages/changelog/2026-03-17.mdx b/fern/products/docs/pages/changelog/2026-03-17.mdx index 514e4951a..2c8bd1c2f 100644 --- a/fern/products/docs/pages/changelog/2026-03-17.mdx +++ b/fern/products/docs/pages/changelog/2026-03-17.mdx @@ -4,13 +4,13 @@ tags: ["seo", "configuration", "docs.yml"] ## Dynamic OG image color overrides [#og-color-overrides] -You can now control the text and background colors of dynamically generated OG images. Set `og:text-color` and `og:background-color` in your `docs.yml` metadata to override the auto-detected theme colors. This is useful when your site has a light background where the default white text is hard to read. +You can now control the text and background colors of dynamically generated OG images. Set `og:dynamic:text-color` and `og:dynamic:background-color` in your `docs.yml` metadata to override the auto-detected theme colors. This is useful when your site has a light background where the default white text is hard to read. ```yaml docs.yml metadata: og:dynamic: true - og:text-color: "#1a1a1a" - og:background-color: "#ffffff" + og:dynamic:text-color: "#1a1a1a" + og:dynamic:background-color: "#ffffff" ``` diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index 81e110d3d..11262b6bd 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -114,8 +114,8 @@ 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:text-color: "#1a1a1a" # optional - og:background-color: "#ffffff" # optional + og:dynamic:text-color: "#1a1a1a" # optional + og:dynamic:background-color: "#ffffff" # optional ``` @@ -126,11 +126,11 @@ 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. - + 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. - + 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. diff --git a/fern/snippets/seo-metadata-site.mdx b/fern/snippets/seo-metadata-site.mdx index 157286095..1d30ffaf7 100644 --- a/fern/snippets/seo-metadata-site.mdx +++ b/fern/snippets/seo-metadata-site.mdx @@ -17,8 +17,8 @@ metadata: # Dynamic OG images (beta) og:dynamic: true og:background-image: "https://developer.squareup.com/images/og-background.png" - og:text-color: "#1a1a1a" - og:background-color: "#ffffff" + og:dynamic:text-color: "#1a1a1a" + og:dynamic:background-color: "#ffffff" # Twitter/X twitter:title: "Square Developer Platform Documentation" @@ -97,11 +97,11 @@ metadata: A custom background image for dynamically generated OG images. Can be a URL or a relative file path. - + 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. - + Override the background color for dynamically generated OG images. Accepts any valid CSS color value. From 25492333005287f07b9d46458dd998df4ff50c8e Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 17 Mar 2026 16:23:19 +0000 Subject: [PATCH 3/4] Fix vale warning: remove time-relative term 'now' Co-Authored-By: Kapil Gowru --- fern/products/docs/pages/changelog/2026-03-17.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/changelog/2026-03-17.mdx b/fern/products/docs/pages/changelog/2026-03-17.mdx index 2c8bd1c2f..64d4a2633 100644 --- a/fern/products/docs/pages/changelog/2026-03-17.mdx +++ b/fern/products/docs/pages/changelog/2026-03-17.mdx @@ -4,7 +4,7 @@ tags: ["seo", "configuration", "docs.yml"] ## Dynamic OG image color overrides [#og-color-overrides] -You can now control the text and background colors of dynamically generated OG images. Set `og:dynamic:text-color` and `og:dynamic:background-color` in your `docs.yml` metadata to override the auto-detected theme colors. This is useful when your site has a light background where the default white text is hard to read. +Control the text and background colors of dynamically generated OG images. Set `og:dynamic:text-color` and `og:dynamic:background-color` in your `docs.yml` metadata to override the auto-detected theme colors. This is useful when your site has a light background where the default white text is hard to read. ```yaml docs.yml metadata: From 046d3e81d37c2656ea27176d8d02334235fa8a9e Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 17 Mar 2026 18:26:27 +0000 Subject: [PATCH 4/4] Add toggle flags documentation and update changelog for OG image redesign Co-Authored-By: Kapil Gowru --- .../docs/pages/changelog/2026-03-17.mdx | 15 +++++++++-- fern/products/docs/pages/seo/metadata.mdx | 25 +++++++++++++++++++ fern/snippets/seo-metadata-site.mdx | 25 +++++++++++++++++++ 3 files changed, 63 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/changelog/2026-03-17.mdx b/fern/products/docs/pages/changelog/2026-03-17.mdx index 64d4a2633..3a32778f9 100644 --- a/fern/products/docs/pages/changelog/2026-03-17.mdx +++ b/fern/products/docs/pages/changelog/2026-03-17.mdx @@ -2,15 +2,26 @@ tags: ["seo", "configuration", "docs.yml"] --- -## Dynamic OG image color overrides [#og-color-overrides] +## Redesigned dynamic OG images [#og-image-redesign] -Control the text and background colors of dynamically generated OG images. Set `og:dynamic:text-color` and `og:dynamic:background-color` in your `docs.yml` metadata to override the auto-detected theme colors. This is useful when your site has a light background where the default white text is hard to read. +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 ``` diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index 11262b6bd..5fa7c6b0b 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -116,6 +116,11 @@ metadata: 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 ``` @@ -134,6 +139,26 @@ metadata: 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. + + Toggle visibility of the logo in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled. + + + + 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. + + + + 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. + + + + Toggle visibility of the page URL in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled. + + + + 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. + + ### Twitter / X Controls how your docs appear in Twitter Card previews when shared on X. diff --git a/fern/snippets/seo-metadata-site.mdx b/fern/snippets/seo-metadata-site.mdx index 1d30ffaf7..4755f8edd 100644 --- a/fern/snippets/seo-metadata-site.mdx +++ b/fern/snippets/seo-metadata-site.mdx @@ -19,6 +19,11 @@ metadata: 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" @@ -105,6 +110,26 @@ metadata: Override the background color for dynamically generated OG images. Accepts any valid CSS color value. + + Toggle visibility of the logo in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled. + + + + Toggle visibility of the section title in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled. + + + + Toggle visibility of the page description in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled. + + + + Toggle visibility of the page URL in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled. + + + + Toggle visibility of the accent gradient overlay in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled. + + The host of your documentation website. This will be used to set the canonical URL for metadata tags and documents like the sitemap.