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 01/10] 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 0000000000..514e4951af --- /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 fbac6cf229..81e110d3d0 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 06b3684f16..1572860952 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 02/10] 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 514e4951af..2c8bd1c2fb 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 81e110d3d0..11262b6bdb 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 1572860952..1d30ffaf75 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 03/10] 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 2c8bd1c2fb..64d4a26338 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 04/10] 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 64d4a26338..3a32778f95 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 11262b6bdb..5fa7c6b0bf 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 1d30ffaf75..4755f8edd1 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. From 37008af6c202172d6d53c2fa116d7ae71e12b426 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 21 Apr 2026 17:44:45 +0000 Subject: [PATCH 05/10] Document og:dynamic:logo-color and add conflicts/precedence note Co-Authored-By: Kapil Gowru --- fern/products/docs/pages/changelog/2026-03-17.mdx | 4 ++++ fern/products/docs/pages/seo/metadata.mdx | 15 +++++++++++++++ fern/snippets/seo-metadata-site.mdx | 5 +++++ 3 files changed, 24 insertions(+) diff --git a/fern/products/docs/pages/changelog/2026-03-17.mdx b/fern/products/docs/pages/changelog/2026-03-17.mdx index 3a32778f95..32fa48e484 100644 --- a/fern/products/docs/pages/changelog/2026-03-17.mdx +++ b/fern/products/docs/pages/changelog/2026-03-17.mdx @@ -7,9 +7,12 @@ tags: ["seo", "configuration", "docs.yml"] 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 title** clamped to two lines with ellipsis - **Page description** extracted from frontmatter, clamped to two lines - **Page URL** displayed below the description - **Dark mode default** with a subtle accent gradient overlay +- **Logo variant selection** with the new `og:dynamic:logo-color` setting (`dark` or `light`) +- **Color overrides** for text and background - **Toggle flags** to show or hide individual elements (logo, section, description, URL, gradient) ```yaml docs.yml @@ -17,6 +20,7 @@ metadata: og:dynamic: true og:dynamic:text-color: "#1a1a1a" og:dynamic:background-color: "#ffffff" + og:dynamic:logo-color: dark og:dynamic:show-logo: true og:dynamic:show-section: true og:dynamic:show-description: true diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index 14bf494d2b..24349b5eb4 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -115,6 +115,7 @@ metadata: og:background-image: ./images/og-background.png # optional og:dynamic:text-color: "#1a1a1a" # optional og:dynamic:background-color: "#ffffff" # optional + og:dynamic:logo-color: dark # optional, dark | light og:dynamic:show-logo: true # optional og:dynamic:show-section: true # optional og:dynamic:show-description: true # optional @@ -138,6 +139,10 @@ 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. + + Choose which logo variant to render in dynamically generated OG images. Accepts `dark` or `light`, matching the corresponding entry under the top-level [`logo:` setting](/learn/docs/getting-started/global-configuration#logo-configuration) in your `docs.yml`. Defaults to `dark`. If your `docs.yml` only defines one logo variant, that variant is used regardless of this setting. + + Toggle visibility of the logo in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled. @@ -158,6 +163,16 @@ metadata: 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. +#### Conflicts and precedence + +When `og:dynamic: true`, the following interactions apply. `fern check` surfaces warnings for each conflict so you can resolve them locally. + +- `og:image` and `twitter:image` only apply to the homepage. Every other page uses the dynamically generated image. +- `og:dynamic:*` sub-settings and `og:background-image` are only read when `og:dynamic: true`. If dynamic generation is off, they are ignored. +- `og:dynamic:logo-color` has no effect when `og:dynamic:show-logo: false`. +- `og:image:width` and `og:image:height` are only used alongside `og:image`. Setting them without `og:image` is a no-op. +- `og:dynamic:text-color` must differ from `og:dynamic:background-color`, otherwise the text becomes invisible. + ### 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 bd717cb4a2..a312d975ae 100644 --- a/fern/snippets/seo-metadata-site.mdx +++ b/fern/snippets/seo-metadata-site.mdx @@ -19,6 +19,7 @@ metadata: og:background-image: "https://developer.squareup.com/images/og-background.png" og:dynamic:text-color: "#1a1a1a" og:dynamic:background-color: "#ffffff" + og:dynamic:logo-color: dark og:dynamic:show-logo: true og:dynamic:show-section: true og:dynamic:show-description: true @@ -110,6 +111,10 @@ metadata: Override the background color for dynamically generated OG images. Accepts any valid CSS color value. + + Choose which logo variant (`dark` or `light`) to render in dynamically generated OG images. Defaults to `dark`. + + Toggle visibility of the logo in dynamically generated OG images. Defaults to `true` when `og:dynamic` is enabled. From 88fe33c2bd3adc19fbe3771857eac64c883c6a1c Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 23 Apr 2026 12:04:56 -0400 Subject: [PATCH 06/10] clarify text + structure --- .../docs/pages/changelog/2026-03-17.mdx | 31 ------------------ .../docs/pages/changelog/2026-04-23.mdx | 15 +++++++++ fern/products/docs/pages/seo/metadata.mdx | 32 ++++--------------- 3 files changed, 22 insertions(+), 56 deletions(-) delete mode 100644 fern/products/docs/pages/changelog/2026-03-17.mdx create mode 100644 fern/products/docs/pages/changelog/2026-04-23.mdx diff --git a/fern/products/docs/pages/changelog/2026-03-17.mdx b/fern/products/docs/pages/changelog/2026-03-17.mdx deleted file mode 100644 index 32fa48e484..0000000000 --- a/fern/products/docs/pages/changelog/2026-03-17.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -tags: ["seo", "configuration", "docs.yml"] ---- - -## Redesigned dynamic OG images [#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 title** clamped to two lines with ellipsis -- **Page description** extracted from frontmatter, clamped to two lines -- **Page URL** displayed below the description -- **Dark mode default** with a subtle accent gradient overlay -- **Logo variant selection** with the new `og:dynamic:logo-color` setting (`dark` or `light`) -- **Color overrides** for text and background -- **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:logo-color: dark - 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/changelog/2026-04-23.mdx b/fern/products/docs/pages/changelog/2026-04-23.mdx new file mode 100644 index 0000000000..9b3b834d24 --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-04-23.mdx @@ -0,0 +1,15 @@ +--- +tags: ["seo", "configuration", "docs.yml"] +--- + +## Redesigned dynamic OG images + +Dynamic OG images have a new layout with fine-grained control over the logo variant, text and background colors, and which elements appear (section, description, URL, gradient). + +```yaml docs.yml +metadata: + og:dynamic: true + og:background-image: ./images/og-background.png +``` + + diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index 24349b5eb4..827e745a29 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -92,11 +92,11 @@ The image displayed when your docs are shared on LinkedIn, Slack, Discord, and o - The width of your Open Graph image in pixels. + The width of your Open Graph image in pixels. Only applied when `og:image` is set. - The height of your Open Graph image in pixels. + The height of your Open Graph image in pixels. Only applied when `og:image` is set. @@ -105,26 +105,18 @@ The image displayed when your docs are shared on LinkedIn, Slack, Discord, and o ### Dynamic OG images [#dynamic-og-images] -Instead of using a single static image for all pages, you can enable dynamic OG image generation. When enabled, Fern automatically generates a unique `og:image` for each page that doesn't have one [set in frontmatter](#open-graph). +Instead of using a single static image for all pages, you can enable dynamic OG image generation. When enabled, Fern automatically generates a unique `og:image` for each page that doesn't have one [set in frontmatter](#open-graph). The `og:dynamic:*` sub-settings and `og:background-image` below are only read when `og:dynamic: true` — they are ignored otherwise. `fern check` surfaces warnings for conflicting settings so you can resolve them locally. You can optionally provide a custom background image (`og:background-image`) for dynamically generated OG images. ```yaml docs.yml 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:logo-color: dark # optional, dark | light - 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 + og:background-image: ./images/og-background.png ``` - When `true`, enables dynamic OG image generation for pages that don't have a custom `og:image` set. + When `true`, enables dynamic OG image generation for pages that don't have a custom `og:image` set. Any site-wide `og:image` and `twitter:image` still apply to the homepage; every other page uses the dynamically generated image. @@ -132,7 +124,7 @@ metadata: - 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 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. Must differ from `og:dynamic:background-color` so the text remains visible. @@ -140,7 +132,7 @@ metadata: - Choose which logo variant to render in dynamically generated OG images. Accepts `dark` or `light`, matching the corresponding entry under the top-level [`logo:` setting](/learn/docs/getting-started/global-configuration#logo-configuration) in your `docs.yml`. Defaults to `dark`. If your `docs.yml` only defines one logo variant, that variant is used regardless of this setting. + Choose which logo variant to render in dynamically generated OG images. Accepts `dark` or `light`, matching the corresponding entry under the top-level [`logo:` setting](/learn/docs/getting-started/global-configuration#logo-configuration) in your `docs.yml`. If your `docs.yml` only defines one logo variant, that variant is used regardless of this setting. Has no effect when `og:dynamic:show-logo: false`. @@ -163,16 +155,6 @@ metadata: 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. -#### Conflicts and precedence - -When `og:dynamic: true`, the following interactions apply. `fern check` surfaces warnings for each conflict so you can resolve them locally. - -- `og:image` and `twitter:image` only apply to the homepage. Every other page uses the dynamically generated image. -- `og:dynamic:*` sub-settings and `og:background-image` are only read when `og:dynamic: true`. If dynamic generation is off, they are ignored. -- `og:dynamic:logo-color` has no effect when `og:dynamic:show-logo: false`. -- `og:image:width` and `og:image:height` are only used alongside `og:image`. Setting them without `og:image` is a no-op. -- `og:dynamic:text-color` must differ from `og:dynamic:background-color`, otherwise the text becomes invisible. - ### Twitter / X Controls how your docs appear in Twitter Card previews when shared on X. From 4a646311e46b2ce5997dd7d535b39ea908488274 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 28 Apr 2026 16:59:47 +0000 Subject: [PATCH 07/10] Add defaults to SEO metadata ParamFields Co-Authored-By: Kapil Gowru --- fern/products/docs/pages/seo/metadata.mdx | 110 +++++++++++----------- fern/snippets/seo-metadata-site.mdx | 74 +++++++-------- 2 files changed, 92 insertions(+), 92 deletions(-) diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index 827e745a29..4b01dd85fd 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -63,23 +63,23 @@ Identity and descriptive fields used by search engines and shared across social The name of your website for Open Graph tags. - - The title shown in social media previews. + + The title shown in social media previews. Falls back to the page's `title` when unset. - - The description shown in social media previews. + + The description shown in social media previews. Falls back to the page's `description`, `subtitle`, or `excerpt` when unset. - - The canonical URL of your documentation. + + The canonical URL of your documentation. Falls back to the page's resolved URL when unset. - The locale of your content (e.g., `en_US`). + The locale of your content (e.g., `en_US`). No default; the tag is omitted when unset. - + The host of your documentation website. Used to set the canonical URL for metadata tags and documents like the sitemap. Defaults to the URL defined in `instances`. @@ -88,7 +88,7 @@ Identity and descriptive fields used by search engines and shared across social The image displayed when your docs are shared on LinkedIn, Slack, Discord, and other platforms. Use a 1200x630px image for the best display across platforms — this is the standard Open Graph size and will render correctly in most previews. Avoid embedding text in the image since it may be cropped on some platforms. - The image shown in social media previews. Recommended size is 1200x630 pixels. + The image shown in social media previews. Recommended size is 1200x630 pixels. No default; the tag is omitted when unset. @@ -100,7 +100,7 @@ The image displayed when your docs are shared on LinkedIn, Slack, Discord, and o - URL to your company logo. + URL to your company logo. No default; the tag is omitted when unset. ### Dynamic OG images [#dynamic-og-images] @@ -120,14 +120,14 @@ metadata: - A custom background image for dynamically generated OG images. Can be a URL or a relative file path. Relative paths are resolved from the YAML file where this property is set (e.g., `docs.yml`). When set, this image is used as the background instead of a solid color. + A custom background image for dynamically generated OG images. Can be a URL or a relative file path. Relative paths are resolved from the YAML file where this property is set (e.g., `docs.yml`). When set, this image is used as the background instead of a solid color. No default; the dynamic OG image renders without a background image when unset. - + 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. Must differ from `og:dynamic:background-color` so the text remains visible. - + 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. @@ -159,27 +159,27 @@ metadata: Controls how your docs appear in Twitter Card previews when shared on X. - - The title shown in Twitter Card previews. + + The title shown in Twitter Card previews. Falls back to `og:title` (and then to the page title) when unset. - - The description shown in Twitter Card previews. + + The description shown in Twitter Card previews. Falls back to `og:description` (and then to the page description) when unset. - Your company's Twitter handle. + Your company's Twitter handle. No default; the tag is omitted when unset. - - The image shown in Twitter Card previews. + + The image shown in Twitter Card previews. Falls back to `og:image` when unset. - The Twitter handle for your website. + The Twitter handle for your website. No default; the tag is omitted when unset. - + The Twitter Card type. Options are `summary`, `summary_large_image`, `app`, or `player`. @@ -213,87 +213,87 @@ nofollow: false Page title, URL, and keyword fields used by search engines. Use `headline` when you need a different title for search engines than what appears as the visible page heading. - + When set, the `` tag in the document head will use this value rather than the `title` property. For example, your `title` might be "Quickstart" (shown in the sidebar and as the H1), while `headline` could be "Quickstart | PlantStore API Docs" to give search engines more context. If not set, Fern uses `title` with your site name appended. </ParamField> -<ParamField path="canonical-url" type="string" required={false} toc={true}> - Overrides the canonical URL for this page. Must be a full URL including the protocol (e.g., `https://buildwithfern.com/learn/docs/content/frontmatter`). +<ParamField path="canonical-url" type="string" required={false} default="Page URL" toc={true}> + Overrides the canonical URL for this page. Must be a full URL including the protocol (e.g., `https://buildwithfern.com/learn/docs/content/frontmatter`). Defaults to the page's resolved URL when unset. </ParamField> <ParamField path="keywords" type="string" required={false} toc={true}> - Comma-separated keywords relevant to the page (e.g., `plants, garden, nursery`). Accepts only comma-separated strings, not arrays. + Comma-separated keywords relevant to the page (e.g., `plants, garden, nursery`). Accepts only comma-separated strings, not arrays. No default; the tag is omitted when unset. </ParamField> ### Open Graph Controls how this page appears when shared on LinkedIn, Slack, Discord, and other platforms that support Open Graph. Keep titles between 50–60 characters and descriptions between 150–160 characters for optimal display. -<ParamField path="og:site_name" type="string" required={false} toc={true}> - The name of your website as it should appear when your content is shared. +<ParamField path="og:site_name" type="string" required={false} default="metadata.og:site_name" toc={true}> + The name of your website as it should appear when your content is shared. Falls back to the site-wide `metadata.og:site_name` from `docs.yml`. </ParamField> -<ParamField path="og:title" type="string" required={false} toc={true}> - The title of your page as it should appear when your content is shared. +<ParamField path="og:title" type="string" required={false} default="Page title" toc={true}> + The title of your page as it should appear when your content is shared. Falls back to the page's `title` when unset. </ParamField> -<ParamField path="og:description" type="string" required={false} toc={true}> - The description of your page as it should appear when your content is shared. +<ParamField path="og:description" type="string" required={false} default="Page description" toc={true}> + The description of your page as it should appear when your content is shared. Falls back to the page's `description`, `subtitle`, or `excerpt` when unset. </ParamField> -<ParamField path="og:url" type="string" required={false} toc={true}> - The URL of your page. +<ParamField path="og:url" type="string" required={false} default="Page URL" toc={true}> + The URL of your page. Falls back to the page's resolved URL when unset. </ParamField> -<ParamField path="og:image" type="string" required={false} toc={true}> - The URL of the image displayed when your content is shared. +<ParamField path="og:image" type="string" required={false} default="metadata.og:image" toc={true}> + The URL of the image displayed when your content is shared. Falls back to the site-wide `metadata.og:image` from `docs.yml`. </ParamField> <ParamField path="og:image:width" type="number" required={false} toc={true}> - The width of the image in pixels. + The width of the image in pixels. No default; only used when `og:image` is set. </ParamField> <ParamField path="og:image:height" type="number" required={false} toc={true}> - The height of the image in pixels. + The height of the image in pixels. No default; only used when `og:image` is set. </ParamField> -<ParamField path="og:locale" type="string" required={false} toc={true}> - The locale of the page, typically in the format `language_TERRITORY` (e.g., `en_US`). +<ParamField path="og:locale" type="string" required={false} default="metadata.og:locale" toc={true}> + The locale of the page, typically in the format `language_TERRITORY` (e.g., `en_US`). Falls back to the site-wide `metadata.og:locale` from `docs.yml`. </ParamField> -<ParamField path="og:logo" type="string" required={false} toc={true}> - The URL of your logo image displayed when your content is shared. +<ParamField path="og:logo" type="string" required={false} default="metadata.og:logo" toc={true}> + The URL of your logo image displayed when your content is shared. Falls back to the site-wide `metadata.og:logo` from `docs.yml`. </ParamField> ### Twitter / X Controls how this page appears in Twitter Card previews when shared on X. -<ParamField path="twitter:title" type="string" required={false} toc={true}> - The title of your page as it should appear in a tweet. +<ParamField path="twitter:title" type="string" required={false} default="og:title" toc={true}> + The title of your page as it should appear in a tweet. Falls back to `og:title` (and then to the page title) when unset. </ParamField> -<ParamField path="twitter:description" type="string" required={false} toc={true}> - The description of your page as it should appear in a tweet. +<ParamField path="twitter:description" type="string" required={false} default="og:description" toc={true}> + The description of your page as it should appear in a tweet. Falls back to `og:description` (and then to the page description) when unset. </ParamField> -<ParamField path="twitter:handle" type="string" required={false} toc={true}> - The Twitter handle of the page creator or site. +<ParamField path="twitter:handle" type="string" required={false} default="metadata.twitter:handle" toc={true}> + The Twitter handle of the page creator or site. Falls back to the site-wide `metadata.twitter:handle` from `docs.yml`. </ParamField> -<ParamField path="twitter:image" type="string" required={false} toc={true}> - The URL of the image displayed in a tweet. +<ParamField path="twitter:image" type="string" required={false} default="og:image" toc={true}> + The URL of the image displayed in a tweet. Falls back to `og:image` when unset. </ParamField> -<ParamField path="twitter:site" type="string" required={false} toc={true}> - The Twitter handle for your website. +<ParamField path="twitter:site" type="string" required={false} default="metadata.twitter:site" toc={true}> + The Twitter handle for your website. Falls back to the site-wide `metadata.twitter:site` from `docs.yml`. </ParamField> -<ParamField path="twitter:url" type="string" required={false} toc={true}> - The URL of your page. +<ParamField path="twitter:url" type="string" required={false} default="og:url" toc={true}> + The URL of your page. Falls back to `og:url` (and then to the page URL) when unset. </ParamField> -<ParamField path="twitter:card" type="string" required={false} toc={true}> +<ParamField path="twitter:card" type="string" required={false} default="summary_large_image" toc={true}> The type of card used for sharing on Twitter. Options: `summary`, `summary_large_image`, `app`, `player`. </ParamField> diff --git a/fern/snippets/seo-metadata-site.mdx b/fern/snippets/seo-metadata-site.mdx index a312d975ae..f064002fc0 100644 --- a/fern/snippets/seo-metadata-site.mdx +++ b/fern/snippets/seo-metadata-site.mdx @@ -39,103 +39,103 @@ metadata: 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 path="metadata.og:title" type="string" required={false} default="Page title"> + The title shown in social media previews. Falls back to the page's `title` when unset. </ParamField> -<ParamField path="metadata.og:description" type="string" required={false}> - The description shown in social media previews. +<ParamField path="metadata.og:description" type="string" required={false} default="Page description"> + The description shown in social media previews. Falls back to the page's `description`, `subtitle`, or `excerpt` when unset. </ParamField> -<ParamField path="metadata.og:url" type="string" required={false}> - The canonical URL of your documentation. +<ParamField path="metadata.og:url" type="string" required={false} default="Page URL"> + The canonical URL of your documentation. Falls back to the page's resolved URL when unset. </ParamField> <ParamField path="metadata.og:image" type="string" required={false}> - The image shown in social media previews. Recommended size is 1200x630 pixels. + The image shown in social media previews. Recommended size is 1200x630 pixels. No default; the tag is omitted when unset. </ParamField> <ParamField path="metadata.og:image:width" type="number" required={false}> - The width of your Open Graph image in pixels. + The width of your Open Graph image in pixels. No default; only used when `og:image` is set. </ParamField> <ParamField path="metadata.og:image:height" type="number" required={false}> - The height of your Open Graph image in pixels. + The height of your Open Graph image in pixels. No default; only used when `og:image` is set. </ParamField> <ParamField path="metadata.og:locale" type="string" required={false}> - The locale of your content (e.g., "en_US"). + The locale of your content (e.g., "en_US"). No default; the tag is omitted when unset. </ParamField> <ParamField path="metadata.og:logo" type="string" required={false}> - URL to your company logo. + URL to your company logo. No default; the tag is omitted when unset. </ParamField> -<ParamField path="metadata.twitter:title" type="string" required={false}> - The title shown in Twitter Card previews. +<ParamField path="metadata.twitter:title" type="string" required={false} default="og:title"> + The title shown in Twitter Card previews. Falls back to `og:title` (and then to the page title) when unset. </ParamField> -<ParamField path="metadata.twitter:description" type="string" required={false}> - The description shown in Twitter Card previews. +<ParamField path="metadata.twitter:description" type="string" required={false} default="og:description"> + The description shown in Twitter Card previews. Falls back to `og:description` (and then to the page description) when unset. </ParamField> <ParamField path="metadata.twitter:handle" type="string" required={false}> - Your company's Twitter handle. + Your company's Twitter handle. No default; the tag is omitted when unset. </ParamField> -<ParamField path="metadata.twitter:image" type="string" required={false}> - The image shown in Twitter Card previews. +<ParamField path="metadata.twitter:image" type="string" required={false} default="og:image"> + The image shown in Twitter Card previews. Falls back to `og:image` when unset. </ParamField> <ParamField path="metadata.twitter:site" type="string" required={false}> - The Twitter handle for your website. + The Twitter handle for your website. No default; the tag is omitted when unset. </ParamField> -<ParamField path="metadata.twitter:card" type="string" required={false}> +<ParamField path="metadata.twitter:card" type="string" required={false} default="summary_large_image"> The Twitter Card type. Options are `summary`, `summary_large_image`, `app`, or `player`. </ParamField> -<ParamField path="metadata.og:dynamic" type="boolean" required={false}> +<ParamField path="metadata.og:dynamic" type="boolean" required={false} default={false}> When `true`, enables dynamic OG image generation for pages that don't have a custom `og:image` set. </ParamField> <ParamField path="metadata.og:background-image" type="string" required={false}> - A custom background image for dynamically generated OG images. Can be a URL or a relative file path. Relative paths are resolved from the YAML file where this property is set (e.g., `docs.yml`). + A custom background image for dynamically generated OG images. Can be a URL or a relative file path. Relative paths are resolved from the YAML file where this property is set (e.g., `docs.yml`). No default; the dynamic OG image renders without a background image when unset. </ParamField> -<ParamField path="metadata.og:dynamic:text-color" type="string" required={false}> +<ParamField path="metadata.og:dynamic:text-color" type="string" required={false} default="Auto-detected from theme"> 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}> +<ParamField path="metadata.og:dynamic:background-color" type="string" required={false} default="Auto-detected from theme"> Override the background color for dynamically generated OG images. Accepts any valid CSS color value. </ParamField> -<ParamField path="metadata.og:dynamic:logo-color" type="enum" required={false}> - Choose which logo variant (`dark` or `light`) to render in dynamically generated OG images. Defaults to `dark`. +<ParamField path="metadata.og:dynamic:logo-color" type="enum" required={false} default="dark"> + Choose which logo variant (`dark` or `light`) to render in dynamically generated OG images. </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 path="metadata.og:dynamic:show-logo" type="boolean" required={false} default={true}> + Toggle visibility of the logo in dynamically generated OG images. </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 path="metadata.og:dynamic:show-section" type="boolean" required={false} default={true}> + Toggle visibility of the section title in dynamically generated OG images. </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 path="metadata.og:dynamic:show-description" type="boolean" required={false} default={true}> + Toggle visibility of the page description in dynamically generated OG images. </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 path="metadata.og:dynamic:show-url" type="boolean" required={false} default={true}> + Toggle visibility of the page URL in dynamically generated OG images. </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 path="metadata.og:dynamic:show-gradient" type="boolean" required={false} default={true}> + Toggle visibility of the accent gradient overlay in dynamically generated OG images. </ParamField> -<ParamField path="metadata.canonical-host" type="string" required={false}> +<ParamField path="metadata.canonical-host" type="string" required={false} default="Instance URL"> The host of your documentation website. This will be used to set the canonical URL for metadata tags and documents like the sitemap. Defaults to the URL defined in the `instances` configuration. From bf9d931ff6f403cf738ea0ac71b57e26c3b401b6 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 29 Apr 2026 16:01:58 +0000 Subject: [PATCH 08/10] Add specific default color values to og:dynamic color ParamFields Co-Authored-By: Devin Logan <devinannlogan@gmail.com> --- fern/products/docs/pages/seo/metadata.mdx | 8 ++++---- fern/snippets/seo-metadata-site.mdx | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index d4fde3d0b4..e457bbc52d 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -131,12 +131,12 @@ metadata: A custom background image for dynamically generated OG images. Can be a URL or a relative file path. Relative paths are resolved from the YAML file where this property is set (e.g., `docs.yml`). When set, this image is used as the background instead of a solid color. No default; the dynamic OG image renders without a background image when unset. </ParamField> -<ParamField path="metadata.og:dynamic:text-color" type="string" required={false} default="Auto-detected from theme" 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. Must differ from `og:dynamic:background-color` so the text remains visible. +<ParamField path="metadata.og:dynamic:text-color" type="string" required={false} default="#ffffff (dark) / #1a1a1a (light)" toc={true}> + Override the text color for dynamically generated OG images. Accepts any valid CSS color value (e.g., `"#1a1a1a"`). By default, Fern reads the text color from your theme (`grayScale[11]`). If no theme color is available, falls back to `#ffffff` for dark mode or `#1a1a1a` for light mode. Must differ from `og:dynamic:background-color` so the text remains visible. </ParamField> -<ParamField path="metadata.og:dynamic:background-color" type="string" required={false} default="Auto-detected from theme" 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 path="metadata.og:dynamic:background-color" type="string" required={false} default="#0A0A0A (dark) / theme background (light)" toc={true}> + Override the background color for dynamically generated OG images. Accepts any valid CSS color value (e.g., `"#ffffff"`). By default, Fern reads the background color from your theme. If no theme color is available, falls back to `#0A0A0A`. </ParamField> <ParamField path="metadata.og:dynamic:logo-color" type="enum" required={false} default="dark" toc={true}> diff --git a/fern/snippets/seo-metadata-site.mdx b/fern/snippets/seo-metadata-site.mdx index f064002fc0..519ad09112 100644 --- a/fern/snippets/seo-metadata-site.mdx +++ b/fern/snippets/seo-metadata-site.mdx @@ -103,12 +103,12 @@ metadata: A custom background image for dynamically generated OG images. Can be a URL or a relative file path. Relative paths are resolved from the YAML file where this property is set (e.g., `docs.yml`). No default; the dynamic OG image renders without a background image when unset. </ParamField> -<ParamField path="metadata.og:dynamic:text-color" type="string" required={false} default="Auto-detected from theme"> - 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 path="metadata.og:dynamic:text-color" type="string" required={false} default="#ffffff (dark) / #1a1a1a (light)"> + Override the text color for dynamically generated OG images. Accepts any valid CSS color value. Auto-detected from your theme; falls back to `#ffffff` (dark) or `#1a1a1a` (light). </ParamField> -<ParamField path="metadata.og:dynamic:background-color" type="string" required={false} default="Auto-detected from theme"> - Override the background color for dynamically generated OG images. Accepts any valid CSS color value. +<ParamField path="metadata.og:dynamic:background-color" type="string" required={false} default="#0A0A0A (dark) / theme background (light)"> + Override the background color for dynamically generated OG images. Accepts any valid CSS color value. Auto-detected from your theme; falls back to `#0A0A0A`. </ParamField> <ParamField path="metadata.og:dynamic:logo-color" type="enum" required={false} default="dark"> From 5e3d7f97dc596b631d3a4efa3a4e2e1213a09368 Mon Sep 17 00:00:00 2001 From: Devin Logan <devinannlogan@gmail.com> Date: Wed, 29 Apr 2026 12:02:59 -0400 Subject: [PATCH 09/10] restructure --- fern/products/docs/pages/seo/metadata.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index d4fde3d0b4..3fb45d3a10 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -1,7 +1,7 @@ --- title: Configure SEO metadata description: Configure SEO metadata in Fern docs with page-level frontmatter and site-wide settings. Control titles, descriptions, social media previews, and sitemap timestamps. -max-toc-depth: 3 +max-toc-depth: 4 --- When you want to customize how your pages appear in search results or social previews, you can set defaults [at the site level](#site-wide-defaults) or override them on [individual pages](#page-level-overrides). @@ -85,7 +85,11 @@ Identity and descriptive fields used by search engines and shared across social ### Social image -The image displayed when your docs are shared on LinkedIn, Slack, Discord, and other platforms. Use a 1200x630px image for the best display across platforms — this is the standard Open Graph size and will render correctly in most previews. Avoid embedding text in the image since it may be cropped on some platforms. +The image displayed when your docs are shared on LinkedIn, Slack, Discord, and other platforms. You can either set a single image that applies to every page, or have Fern dynamically generate a unique image per page. + +#### Manual + +Set one static image with `og:image` that applies to every page. Use a 1200x630px image for the best display across platforms — this is the standard Open Graph size and will render correctly in most previews. Avoid embedding text in the image since it may be cropped on some platforms. <ParamField path="metadata.og:image" type="string" required={false} toc={true}> The image shown in social media previews. Recommended size is 1200x630 pixels. No default; the tag is omitted when unset. @@ -103,7 +107,7 @@ The image displayed when your docs are shared on LinkedIn, Slack, Discord, and o URL to your company logo. No default; the tag is omitted when unset. </ParamField> -### Dynamic OG images <Availability type="beta" /> [#dynamic-og-images] +#### Dynamic <Availability type="beta" /> [#dynamic-og-images] Instead of using a single static image for all pages, you can enable dynamic OG image generation. When enabled, Fern automatically generates a unique `og:image` for each page that doesn't have one [set in frontmatter](#open-graph). The `og:dynamic:*` sub-settings and `og:background-image` below are only read when `og:dynamic: true` — they're ignored otherwise. `fern check` surfaces warnings for conflicting settings so you can resolve them locally. From 93b461a2c1948412896d42180cccb522ba70c604 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 29 Apr 2026 16:19:23 +0000 Subject: [PATCH 10/10] Add all new properties to changelog YAML example Co-Authored-By: Devin Logan <devinannlogan@gmail.com> --- fern/products/docs/pages/changelog/2026-04-29.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/fern/products/docs/pages/changelog/2026-04-29.mdx b/fern/products/docs/pages/changelog/2026-04-29.mdx index 034e02f0c8..713d800000 100644 --- a/fern/products/docs/pages/changelog/2026-04-29.mdx +++ b/fern/products/docs/pages/changelog/2026-04-29.mdx @@ -10,6 +10,14 @@ Dynamic OG images have a new layout with fine-grained control over the logo vari metadata: og:dynamic: true og:background-image: ./images/og-background.png + og:dynamic:text-color: "#1a1a1a" + og:dynamic:background-color: "#ffffff" + og:dynamic:logo-color: dark + 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>