Document redesigned dynamic OG images with toggle flags and color overrides by kgowru · Pull Request #4322 · fern-api/docs

kgowru · 2026-03-17T15:22:06Z

Summary

Documents the redesigned dynamic OG image feature, adding eight new docs.yml metadata settings that match the current implementation in fern-platform and fern CLI:

Color overrides: og:dynamic:text-color and og:dynamic:background-color — override auto-detected theme colors
Logo variant: og:dynamic:logo-color — choose dark or light logo variant
Toggle flags: og:dynamic:show-logo, og:dynamic:show-section, og:dynamic:show-description, og:dynamic:show-url, og:dynamic:show-gradient — show/hide individual OG image elements

Changes:

metadata.mdx: Added ParamField entries for all 8 new settings, expanded the YAML example block, added default values and fallback descriptions to all existing fields
seo-metadata-site.mdx: Added the new fields to the snippet YAML example and ParamField list
changelog/2026-04-29.mdx: Changelog entry for the OG image redesign

Companion PRs (both merged):

fern-platform (rendering + SDK types): https://github.com/fern-api/fern-platform/pull/8677
fern (CLI schema + API definition): feat(docs): add og:dynamic color overrides and element visibility toggle flags fern#13628

Review & Testing Checklist for Human

Preview the metadata page and confirm the 8 new ParamField entries render correctly under "Dynamic OG images" — verify default={true} on toggle flags and default="dark" on og:dynamic:logo-color
Confirm the YAML example block in metadata.mdx and the snippet in seo-metadata-site.mdx list the same 8 fields
Verify the changelog entry at /learn/docs/changelog/2026/4/29 renders correctly and the "Read the docs" button links to the right anchor

Notes

The changelog was moved from 2026-04-23.mdx to 2026-04-29.mdx because the original date was already taken by an unrelated entry on main. Merge conflicts with main have been resolved. The docs.yml tag was removed from changelog tags to match convention.

Link to Devin session: https://app.devin.ai/sessions/248116ef41de45f28f0d8e0c7ad540de
Requested by: @devalog

… entry Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

devin-ai-integration · 2026-03-17T15:22:10Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment and CI monitoring

github-actions · 2026-03-17T15:23:22Z

🌿 Preview your docs: https://fern-preview-devin-1773760543-og-text-color-docs.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

github-actions · 2026-03-17T15:26:32Z

+
+## Dynamic OG image color overrides <Availability type="beta" /> [#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.


⚠️ [vale] _{reported by reviewdog 🐶}
[FernStyles.Current] Avoid time-relative terms like 'now' that become outdated

…dynamic:background-color Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

github-actions · 2026-03-17T16:10:33Z

+
+## Dynamic OG image color overrides <Availability type="beta" /> [#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.


⚠️ [vale] _{reported by reviewdog 🐶}
[FernStyles.Current] Avoid time-relative terms like 'now' that become outdated

Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

…sign Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

github-actions · 2026-04-12T02:19:13Z

This PR is stale because it has been open 25 days with no activity. Remove stale label or comment or this will be closed in 5 days.

github-actions · 2026-04-20T23:53:19Z

+<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>
+


📝 [vale] _{reported by reviewdog 🐶}
[FernStyles.Headings] 'Twitter / X' should use sentence-style capitalization.

Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

github-actions · 2026-04-21T17:45:25Z

+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.


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Contractions] Use 'they're' instead of 'they are'.

github-actions · 2026-04-23T16:11:27Z


 <ParamField path="metadata.og:image:width" type="number" required={false} toc={true}>
-  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.


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Units] Don't spell out the number in 'in pixels'.

github-actions · 2026-04-23T16:11:27Z


 <ParamField path="metadata.og:image:height" type="number" required={false} toc={true}>
-  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.


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Units] Don't spell out the number in 'in pixels'.

github-actions · 2026-04-23T16:11:27Z

 ### Dynamic OG images <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).
+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.


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Contractions] Use 'they're' instead of 'they are'.

devin-ai-integration · 2026-04-23T18:22:51Z

❌ Cannot revive Devin session - the session is too old. Please start a new session instead.

Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>

github-actions · 2026-04-29T15:53:51Z


 <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.


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Units] Don't spell out the number in 'in pixels'.

github-actions · 2026-04-29T15:53:51Z


 <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.


🚫 [vale] _{reported by reviewdog 🐶}
[Microsoft.Units] Don't spell out the number in 'in pixels'.

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>

…com/fern-api/docs into devin/1773760543-og-text-color-docs

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>

Add og:text-color and og:background-color documentation and changelog…

7548309

… entry Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

kgowru requested a review from devalog as a code owner March 17, 2026 15:22

devin-ai-integration Bot assigned kgowru Mar 17, 2026

github-actions Bot reviewed Mar 17, 2026

View reviewed changes

Rename og:text-color/og:background-color to og:dynamic:text-color/og:…

9fee39d

…dynamic:background-color Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

github-actions Bot reviewed Mar 17, 2026

View reviewed changes

devin-ai-integration Bot changed the title ~~Add og:text-color and og:background-color documentation and changelog~~ Add og:dynamic:text-color and og:dynamic:background-color documentation and changelog Mar 17, 2026

devin-ai-integration Bot and others added 2 commits March 17, 2026 16:23

Fix vale warning: remove time-relative term 'now'

2549233

Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

Add toggle flags documentation and update changelog for OG image rede…

046d3e8

…sign Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

devin-ai-integration Bot changed the title ~~Add og:dynamic:text-color and og:dynamic:background-color documentation and changelog~~ Document redesigned dynamic OG images with toggle flags and color overrides Mar 17, 2026

github-actions Bot added the Stale This PR hasn't has any commits or comments in 25 days or more. label Apr 12, 2026

devalog closed this Apr 15, 2026

devin-ai-integration Bot reopened this Apr 20, 2026

github-actions Bot reviewed Apr 20, 2026

View reviewed changes

Merge branch 'main' into devin/1773760543-og-text-color-docs

90b1776

github-actions Bot removed the Stale This PR hasn't has any commits or comments in 25 days or more. label Apr 21, 2026

Document og:dynamic:logo-color and add conflicts/precedence note

37008af

Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

github-actions Bot reviewed Apr 21, 2026

View reviewed changes

clarify text + structure

88fe33c

devalog approved these changes Apr 23, 2026

View reviewed changes

github-actions Bot reviewed Apr 23, 2026

View reviewed changes

devin-ai-integration Bot and others added 2 commits April 28, 2026 17:00

Add defaults to SEO metadata ParamFields

4a64631

Co-Authored-By: Kapil Gowru <k.gowru@gmail.com>

Merge branch 'main' into devin/1773760543-og-text-color-docs

a8537a2

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>

github-actions Bot reviewed Apr 29, 2026

View reviewed changes

devin-ai-integration Bot and others added 2 commits April 29, 2026 16:01

Add specific default color values to og:dynamic color ParamFields

bf9d931

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>

restructure

5e3d7f9

Merge branch 'devin/1773760543-og-text-color-docs' of https://github.…

d25ee72

…com/fern-api/docs into devin/1773760543-og-text-color-docs

devalog approved these changes Apr 29, 2026

View reviewed changes

Add all new properties to changelog YAML example

93b461a

Co-Authored-By: Devin Logan <devinannlogan@gmail.com>

devalog merged commit 152aca5 into main Apr 29, 2026
2 checks passed

devalog deleted the devin/1773760543-og-text-color-docs branch April 29, 2026 16:23


		## Dynamic OG image color overrides <Availability type="beta" /> [#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.

Conversation

kgowru commented Mar 17, 2026 • edited by devin-ai-integration Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Review & Testing Checklist for Human

Notes

Uh oh!

devin-ai-integration Bot commented Mar 17, 2026

🤖 Devin AI Engineer

Uh oh!

github-actions Bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 12, 2026

Uh oh!

github-actions Bot Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot commented Apr 23, 2026

Uh oh!

github-actions Bot Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kgowru commented Mar 17, 2026 •

edited by devin-ai-integration Bot

Loading

github-actions Bot commented Mar 17, 2026 •

edited

Loading