From 374c4547b09a1d887340a932b02825530063d956 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 4 Nov 2025 17:21:12 +0000 Subject: [PATCH 1/3] docs: document what Fern auto-generates for SEO metadata Co-Authored-By: Chris McDonnell --- fern/products/docs/pages/seo/metadata.mdx | 41 ++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index b70bb49c7..69db77979 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -3,12 +3,51 @@ title: Configure SEO metadata description: Configure SEO metadata at the page or site level. --- -Configure SEO metadata at the page or site level to improve search visibility and social media previews for your documentation. Keep titles between 50-60 characters and descriptions between 150-160 characters for optimal display. +Fern automatically generates SEO metadata for every page in your documentation site. You can configure default metadata at the site level and override it on individual pages to improve search visibility and social media previews. Keep titles between 50-60 characters and descriptions between 150-160 characters for optimal display. The metadata configurations on this page are for SEO and social tags that aren't visible to users. For visible footer links, see [footer links configuration](/learn/docs/configuration/what-is-docs-yml#footer-links-configuration). +## What Fern auto-generates + +Fern automatically generates the following SEO metadata for every page in your documentation: + +**HTML meta tags:** +- `` tag with site-wide suffix (e.g., "Page Title | Your Site Name") +- Meta description tag (from `description`, `subtitle`, or `excerpt` fields) +- Meta keywords tag (when keywords are provided) +- Canonical URL (automatically constructed from page slug or custom override) +- Robots meta tags (noindex/nofollow when configured) +- Favicon link tag + +**Open Graph tags for social media:** +- `og:title` - Title shown in social media previews +- `og:description` - Description shown in social media previews +- `og:image` - Image shown in social media previews +- `og:url` - Canonical URL of the page +- `og:site_name` - Name of your website +- `og:locale` - Content locale (e.g., "en_US") +- `og:image:width` and `og:image:height` - Image dimensions + +**Twitter Card tags:** +- `twitter:title` - Title shown in Twitter previews +- `twitter:description` - Description shown in Twitter previews +- `twitter:image` - Image shown in Twitter previews +- `twitter:site` - Twitter handle for your website +- `twitter:creator` - Twitter handle of the content creator +- `twitter:card` - Card type (e.g., "summary_large_image") + +**Intelligent fallback system:** + +Fern uses a three-tier fallback system to ensure every page has appropriate metadata: + +1. **Page-level configuration** (highest priority) - Values from page frontmatter +2. **Site-level configuration** - Default values from `docs.yml` +3. **Sensible defaults** - Automatically generated from page content + +For example, if a page doesn't specify an `og:image`, Fern will use the site-wide `og:image` from `docs.yml`. If no image is configured at either level, the tag is omitted rather than using a broken or placeholder image. + ## Page metadata Set SEO properties in each page's [frontmatter](/docs/configuration/page-level-settings) to control how individual pages appear in search results and social media shares. Page-level metadata takes precedence over site-wide settings. From 386d5024d5feb1b8987a8e62e41a7e753c7dd99a Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 4 Nov 2025 17:23:50 +0000 Subject: [PATCH 2/3] fix: change 'auto-generates' to 'automatically generates' per Vale Co-Authored-By: Chris McDonnell <chris@buildwithfern.com> --- fern/products/docs/pages/seo/metadata.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index 69db77979..1c03235b2 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -9,7 +9,7 @@ Fern automatically generates SEO metadata for every page in your documentation s The metadata configurations on this page are for SEO and social tags that aren't visible to users. For visible footer links, see [footer links configuration](/learn/docs/configuration/what-is-docs-yml#footer-links-configuration). </Note> -## What Fern auto-generates +## What Fern automatically generates Fern automatically generates the following SEO metadata for every page in your documentation: From 17896dacf3954d14df2c1dbaf58944668ef9d37f Mon Sep 17 00:00:00 2001 From: Devin Logan <devinannlogan@gmail.com> Date: Tue, 4 Nov 2025 13:15:26 -0500 Subject: [PATCH 3/3] restructure info --- fern/products/docs/pages/seo/metadata.mdx | 77 ++++++++++++----------- 1 file changed, 40 insertions(+), 37 deletions(-) diff --git a/fern/products/docs/pages/seo/metadata.mdx b/fern/products/docs/pages/seo/metadata.mdx index 1c03235b2..dd8cad0bc 100644 --- a/fern/products/docs/pages/seo/metadata.mdx +++ b/fern/products/docs/pages/seo/metadata.mdx @@ -3,59 +3,62 @@ title: Configure SEO metadata description: Configure SEO metadata at the page or site level. --- -Fern automatically generates SEO metadata for every page in your documentation site. You can configure default metadata at the site level and override it on individual pages to improve search visibility and social media previews. Keep titles between 50-60 characters and descriptions between 150-160 characters for optimal display. +Fern automatically generates all SEO metadata for every page in your documentation site. Search engines and social media previews work out of the box with no configuration required. + +When you do want to customize SEO settings, you can set defaults [at the site level](#website-metadata) or override them on [individual pages](#page-level-configuration). Keep titles between 50-60 characters and descriptions between 150-160 characters for optimal display. <Note> The metadata configurations on this page are for SEO and social tags that aren't visible to users. For visible footer links, see [footer links configuration](/learn/docs/configuration/what-is-docs-yml#footer-links-configuration). </Note> +## How it works + +Fern looks for metadata values in this order: + +1. **Page frontmatter** - Custom SEO values for a specific page +2. **Site-level `docs.yml`** - Default SEO values for all pages +3. **Automatic defaults** - Generated from your page's existing title, description, etc. + +<Info title="Example"> + `og:image` is the image that appears in social media previews. If you don't set `og:image` in a page's frontmatter, Fern uses the site-wide `og:image` from `docs.yml`. If neither is configured, the tag is omitted entirely. +</Info> + + ## What Fern automatically generates -Fern automatically generates the following SEO metadata for every page in your documentation: +For every page, Fern creates these SEO tags in your HTML: -**HTML meta tags:** +<AccordionGroup> +<Accordion title="HTML meta tags"> - `<title>` tag with site-wide suffix (e.g., "Page Title | Your Site Name") -- Meta description tag (from `description`, `subtitle`, or `excerpt` fields) -- Meta keywords tag (when keywords are provided) -- Canonical URL (automatically constructed from page slug or custom override) -- Robots meta tags (noindex/nofollow when configured) +- Meta description (pulled from your `description`, `subtitle`, or `excerpt` fields) +- Meta keywords (when you provide them) +- Canonical URL (from your page slug or `canonical-url` override) +- Robots meta tags (`noindex`/`nofollow` when configured) - Favicon link tag - -**Open Graph tags for social media:** -- `og:title` - Title shown in social media previews -- `og:description` - Description shown in social media previews -- `og:image` - Image shown in social media previews +</Accordion> +<Accordion title="Open Graph tags (for LinkedIn, Slack, Discord, etc.)"> +- `og:title`, `og:description`, `og:image` - What appears in social previews - `og:url` - Canonical URL of the page -- `og:site_name` - Name of your website -- `og:locale` - Content locale (e.g., "en_US") -- `og:image:width` and `og:image:height` - Image dimensions - -**Twitter Card tags:** -- `twitter:title` - Title shown in Twitter previews -- `twitter:description` - Description shown in Twitter previews -- `twitter:image` - Image shown in Twitter previews -- `twitter:site` - Twitter handle for your website -- `twitter:creator` - Twitter handle of the content creator +- `og:site_name` - Your website name +- `og:locale` - Content language (e.g., "en_US") +- `og:image:width`, `og:image:height` - Image dimensions +</Accordion> +<Accordion title="Twitter Card tags"> +- `twitter:title`, `twitter:description`, `twitter:image` - What appears in Twitter/X previews +- `twitter:site`, `twitter:creator` - Your Twitter handles - `twitter:card` - Card type (e.g., "summary_large_image") +</Accordion> +</AccordionGroup> -**Intelligent fallback system:** - -Fern uses a three-tier fallback system to ensure every page has appropriate metadata: +## Website metadata -1. **Page-level configuration** (highest priority) - Values from page frontmatter -2. **Site-level configuration** - Default values from `docs.yml` -3. **Sensible defaults** - Automatically generated from page content +Set default SEO metadata for your entire documentation site in [`docs.yml`](/docs/configuration/what-is-docs-yml). These settings apply to all pages unless overridden by page-specific metadata. -For example, if a page doesn't specify an `og:image`, Fern will use the site-wide `og:image` from `docs.yml`. If no image is configured at either level, the tag is omitted rather than using a broken or placeholder image. +<Markdown src="/snippets/seo-metadata-site.mdx" /> -## Page metadata +## Page-level configuration -Set SEO properties in each page's [frontmatter](/docs/configuration/page-level-settings) to control how individual pages appear in search results and social media shares. Page-level metadata takes precedence over site-wide settings. +Configure SEO metadata in your page's [frontmatter](/docs/configuration/page-level-settings) to control how individual pages appear in search results and social media shares. These settings override site-wide settings. <Markdown src="/snippets/seo-metadata-page.mdx" /> - -## Website metadata - -Define default SEO properties for your entire documentation site in your [`docs.yml` file](/docs/configuration/what-is-docs-yml). These settings apply to all pages unless overridden by page-specific metadata. - -<Markdown src="/snippets/seo-metadata-site.mdx" />