restructure info

Author: devalog

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" />