# Configure SEO metadata

> Configure SEO metadata in Fern docs with page-level frontmatter and site-wide settings. Control titles, descriptions, and social media previews.

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/site-level-settings#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

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

Set default SEO metadata for your entire documentation site in [`docs.yml`](/docs/configuration/site-level-settings). These settings apply to all pages unless overridden by page-specific metadata.

```yaml docs.yml
metadata:
  # Core platform identity
  og:site_name: "Square Developer Documentation"
  og:title: "Square Developer Platform | Payments, Commerce & Banking APIs"
  og:description: "Build with Square's suite of APIs and SDKs. Accept payments, manage inventory, create loyalty programs, and access financial services. Complete documentation for developers building the future of commerce."
  og:url: "https://developer.squareup.com/docs"

  # Social sharing assets
  og:image: "https://developer.squareup.com/images/docs-social-card.png"
  og:image:width: 1200
  og:image:height: 630
  og:locale: "en_US"
  og:logo: "https://developer.squareup.com/images/square-logo.png"

  # Twitter (I mean X) optimization
  twitter:title: "Square Developer Platform Documentation"
  twitter:description: "Integrate payments, point-of-sale, inventory, and financial services into your applications with Square's developer platform. Get started with our APIs, SDKs, and comprehensive guides."
  twitter:handle: "@SquareDev"
  twitter:image: "https://developer.squareup.com/images/twitter-card.png"
  twitter:site: "@Square"
  twitter:card: "summary_large_image"
```

<ParamField path="metadata.og:site_name" type="string" required={false}>
  The name of your website for Open Graph tags.
</ParamField>

<ParamField path="metadata.og:title" type="string" required={false}>
  The title shown in social media previews.
</ParamField>

<ParamField path="metadata.og:description" type="string" required={false}>
  The description shown in social media previews.
</ParamField>

<ParamField path="metadata.og:url" type="string" required={false}>
  The canonical URL of your documentation.
</ParamField>

<ParamField path="metadata.og:image" type="string" required={false}>
  The image shown in social media previews. Recommended size is 1200x630 pixels.
</ParamField>

<ParamField path="metadata.og:image:width" type="number" required={false}>
  The width of your Open Graph image in pixels.
</ParamField>

<ParamField path="metadata.og:image:height" type="number" required={false}>
  The height of your Open Graph image in pixels.
</ParamField>

<ParamField path="metadata.og:locale" type="string" required={false}>
  The locale of your content (e.g., "en\_US").
</ParamField>

<ParamField path="metadata.og:logo" type="string" required={false}>
  URL to your company logo.
</ParamField>

<ParamField path="metadata.twitter:title" type="string" required={false}>
  The title shown in Twitter Card previews.
</ParamField>

<ParamField path="metadata.twitter:description" type="string" required={false}>
  The description shown in Twitter Card previews.
</ParamField>

<ParamField path="metadata.twitter:handle" type="string" required={false}>
  Your company's Twitter handle.
</ParamField>

<ParamField path="metadata.twitter:image" type="string" required={false}>
  The image shown in Twitter Card previews.
</ParamField>

<ParamField path="metadata.twitter:site" type="string" required={false}>
  The Twitter handle for your website.
</ParamField>

<ParamField path="metadata.twitter:card" type="string" required={false}>
  The Twitter Card type. Options are `summary`, `summary_large_image`, `app`, or `player`.
</ParamField>

<ParamField path="metadata.canonical-host" type="string" required={false}>
  The host of your documentation website. This will be used to set the canonical URL for metadata tags and documents like the sitemap.

  Defaults to the URL defined in the `instances` configuration.
</ParamField>

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

<Info>
  Only the documented SEO fields are added to the HTML `<head>` as meta tags. Custom frontmatter fields won't automatically appear in your page metadata. To add custom metadata, use [custom JavaScript](/learn/docs/customization/custom-css-js#custom-javascript).
</Info>

<CodeBlock title="plantstore-quickstart.mdx">
  ```mdx
  ---
  title: PlantStore API Quick Start
  headline: "Get Started with PlantStore API | Developer Documentation"
  keywords: plants, garden, nursery
  canonical-url: https://docs.plantstore.dev/welcome
  og:site_name: PlantStore Developer Documentation
  og:title: "PlantStore API Quick Start Guide"
  og:description: "Learn how to integrate with PlantStore's API to manage plant inventory, process orders, and track shipments. Complete with code examples."
  og:image: https://plantstore.dev/images/api-docs-banner.png
  og:image:width: 1200
  og:image:height: 630
  twitter:card: summary_large_image
  twitter:site: "@PlantStoreAPI"
  noindex: false
  nofollow: false
  ---
  ```
</CodeBlock>

<AccordionGroup>
  <Accordion title="Document properties">
    <ParamField path="headline" type="string" required={false}>
      When set, the `<title />` tag in the document head will use this value rather than the `title` property. This property changes the title that search engines see when crawling this page, and can be used to address Duplicate Title issues in your SEO report.
    </ParamField>

    <ParamField path="canonical-url" type="string" required={false} toc={true}>
      Overrides the canonical URL for this page. Must be a full URL including the protocol (i.e. `https://buildwithfern.com/learn/docs/content/frontmatter`)
    </ParamField>

    <ParamField path="keywords" type="string" required={false}>
      Comma-separated string of keywords relevant to the page content (i.e. `plants, garden, nursery`). These keywords help search engines understand the page topic and contributes to search rankings. Use specific, relevant terms that users might search for when looking for the page's content.

      This field accepts only comma-separated strings, not bracketed arrays.
    </ParamField>
  </Accordion>

  <Accordion title="OpenGraph properties">
    <ParamField path="og:site_name" type="string" required={false}>
      The name of your website as it should appear when your content is shared.
    </ParamField>

    <ParamField path="og:title" type="string" required={false}>
      The title of your page as it should appear when your content is shared.
    </ParamField>

    <ParamField path="og:description" type="string" required={false}>
      The description of your page as it should appear when your content is shared.
    </ParamField>

    <ParamField path="og:url" type="string" required={false}>
      The URL of your page.
    </ParamField>

    <ParamField path="og:image" type="string" required={false}>
      The URL or identifier of the image that will be displayed when your content is shared.
    </ParamField>

    <ParamField path="og:image:width" type="number" required={false}>
      The width of the image in pixels.
    </ParamField>

    <ParamField path="og:image:height" type="number" required={false}>
      The height of the image in pixels.
    </ParamField>

    <ParamField path="og:locale" type="string" required={false}>
      The locale of the page, typically in the format `language_TERRITORY` (e.g., `en_US`).
    </ParamField>

    <ParamField path="og:logo" type="string" required={false}>
      The URL or identifier of the logo image of your website that will be displayed when your content is shared.
    </ParamField>
  </Accordion>

  <Accordion title="Twitter properties">
    <ParamField path="twitter:title" type="string" required={false}>
      The title of your page as it should appear in a tweet.
    </ParamField>

    <ParamField path="twitter:description" type="string" required={false}>
      The description of your page as it should appear in a tweet.
    </ParamField>

    <ParamField path="twitter:handle" type="string" required={false}>
      The Twitter handle of the page creator or site.
    </ParamField>

    <ParamField path="twitter:image" type="string" required={false}>
      The URL or identifier of the image that will be displayed in a tweet.
    </ParamField>

    <ParamField path="twitter:site" type="string" required={false}>
      The name of your website as it should appear in a tweet.
    </ParamField>

    <ParamField path="twitter:url" type="string" required={false}>
      The URL of your page.
    </ParamField>

    <ParamField path="twitter:card" type="string" required={false}>
      The type of card to be used for sharing on Twitter. Options: `summary`, `summary_large_image`, `app`, `player`
    </ParamField>
  </Accordion>

  <Accordion title="Indexing properties">
    <ParamField path="noindex" type="boolean" required={false} default={false} toc={true}>
      If set to `true`, the page will not be indexed by search engines and will be excluded from [llms.txt](/learn/docs/ai-features/llms-txt) endpoints.
    </ParamField>

    <ParamField path="nofollow" type="boolean" required={false} default={false} toc={true}>
      If set to `true`, a search engine will not follow any links present on the page.
    </ParamField>
  </Accordion>
</AccordionGroup>