docs: document what Fern auto-generates for SEO metadata (#1751)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Chris McDonnell <[email protected]>
Co-authored-by: Devin Logan <[email protected]>

Author: 3 people

fern/products/docs/pages/seo/metadata.mdx

@@ -3,20 +3,62 @@ 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 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>
 
-## Page metadata
+## How it works
 
-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.
+Fern looks for metadata values in this order:
 
-<Markdown src="/snippets/seo-metadata-page.mdx" />
+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
+
+For every page, Fern creates these SEO tags in your HTML:
+
+<AccordionGroup>
+<Accordion title="HTML meta tags">
+- `<title>` tag with site-wide suffix (e.g., "Page Title | Your Site Name")
+- 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
+</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` - 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>
 
 ## 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.
+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.
 
 <Markdown src="/snippets/seo-metadata-site.mdx" />
+
+## Page-level configuration
+
+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" />