Document redesigned dynamic OG images with toggle flags and color overrides #4322
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` | ||
|
|
||
| <Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/seo/setting-seo-metadata#dynamic-og-images">Read the docs</Button> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -92,11 +92,11 @@ The image displayed when your docs are shared on LinkedIn, Slack, Discord, and o | |
| </ParamField> | ||
|
|
||
| <ParamField path="metadata.og:image:width" type="number" required={false} toc={true}> | ||
| The width of your Open Graph image in pixels. Only applied when `og:image` is set. | ||
| </ParamField> | ||
|
|
||
| <ParamField path="metadata.og:image:height" type="number" required={false} toc={true}> | ||
| The height of your Open Graph image in pixels. Only applied when `og:image` is set. | ||
|
Contributor
There was a problem hiding this comment. 🚫 [vale] reported by reviewdog 🐶 |
||
| </ParamField> | ||
|
|
||
| <ParamField path="metadata.og:logo" type="string" required={false} toc={true}> | ||
|
|
@@ -105,24 +105,56 @@ The image displayed when your docs are shared on LinkedIn, Slack, Discord, and o | |
|
|
||
| ### 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). 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. | ||
|
Contributor
There was a problem hiding this comment. 🚫 [vale] reported by reviewdog 🐶 |
||
|
|
||
| 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 | ||
| ``` | ||
|
|
||
| <ParamField path="metadata.og:dynamic" type="boolean" required={false} default={false} toc={true}> | ||
| 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. | ||
| </ParamField> | ||
|
|
||
| <ParamField path="metadata.og:background-image" type="string" required={false} toc={true}> | ||
| 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. | ||
| </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. Must differ from `og:dynamic:background-color` so the text remains visible. | ||
| </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:logo-color" type="enum" required={false} default="dark" toc={true}> | ||
| 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`. | ||
| </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> | ||
|
|
||
|
Contributor
There was a problem hiding this comment. 📝 [vale] reported by reviewdog 🐶 |
||
| ### Twitter / X | ||
|
|
||
| Controls how your docs appear in Twitter Card previews when shared on X. | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Units] Don't spell out the number in 'in pixels'.