SEO & GEO

Configure SEO metadata

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 or override them on individual pages. 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.

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

What Fern automatically generates

For every page, Fern creates these SEO tags in your HTML:

  • <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
  • 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
  • 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”)

Website metadata

Set default SEO metadata for your entire documentation site in docs.yml. These settings apply to all pages unless overridden by page-specific metadata.

docs.yml
1metadata:
2  # Core platform identity
3  og:site_name: "Square Developer Documentation"
4  og:title: "Square Developer Platform | Payments, Commerce & Banking APIs"
5  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."
6  og:url: "https://developer.squareup.com/docs"
7
8  # Social sharing assets
9  og:image: "https://developer.squareup.com/images/docs-social-card.png"
10  og:image:width: 1200
11  og:image:height: 630
12  og:locale: "en_US"
13  og:logo: "https://developer.squareup.com/images/square-logo.png"
14
15  # Twitter (I mean X) optimization
16  twitter:title: "Square Developer Platform Documentation"
17  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."
18  twitter:handle: "@SquareDev"
19  twitter:image: "https://developer.squareup.com/images/twitter-card.png"
20  twitter:site: "@Square"
21  twitter:card: "summary_large_image"
metadata.og:site_name
string

The name of your website for Open Graph tags.

metadata.og:title
string

The title shown in social media previews.

metadata.og:description
string

The description shown in social media previews.

metadata.og:url
string

The canonical URL of your documentation.

metadata.og:image
string

The image shown in social media previews. Recommended size is 1200x630 pixels.

metadata.og:image:width
number

The width of your Open Graph image in pixels.

metadata.og:image:height
number

The height of your Open Graph image in pixels.

metadata.og:locale
string

The locale of your content (e.g., “en_US”).

metadata.og:logo
string

URL to your company logo.

metadata.twitter:title
string

The title shown in Twitter Card previews.

metadata.twitter:description
string

The description shown in Twitter Card previews.

metadata.twitter:handle
string

Your company’s Twitter handle.

metadata.twitter:image
string

The image shown in Twitter Card previews.

metadata.twitter:site
string

The Twitter handle for your website.

metadata.twitter:card
string

The Twitter Card type. Options are summary, summary_large_image, app, or player.

metadata.canonical-host
string

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.

Page-level configuration

Configure SEO metadata in your page’s frontmatter to control how individual pages appear in search results and social media shares. These settings override site-wide settings.

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.

plantstore-quickstart.mdx
1---
2title: PlantStore API Quick Start
3headline: "Get Started with PlantStore API | Developer Documentation"
4keywords: plants, garden, nursery
5canonical-url: https://docs.plantstore.dev/welcome
6og:site_name: PlantStore Developer Documentation
7og:title: "PlantStore API Quick Start Guide"
8og:description: "Learn how to integrate with PlantStore's API to manage plant inventory, process orders, and track shipments. Complete with code examples."
9og:image: https://plantstore.dev/images/api-docs-banner.png
10og:image:width: 1200
11og:image:height: 630
12twitter:card: summary_large_image
13twitter:site: "@PlantStoreAPI"
14noindex: false
15nofollow: false
16---
headline
string

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.

canonical-url
string

Overrides the canonical URL for this page. Must be a full URL including the protocol (i.e. https://buildwithfern.com/learn/docs/content/frontmatter)

keywords
string

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.

og:site_name
string

The name of your website as it should appear when your content is shared.

og:title
string

The title of your page as it should appear when your content is shared.

og:description
string

The description of your page as it should appear when your content is shared.

og:url
string

The URL of your page.

og:image
string

The URL or identifier of the image that will be displayed when your content is shared.

og:image:width
number

The width of the image in pixels.

og:image:height
number

The height of the image in pixels.

og:locale
string

The locale of the page, typically in the format language_TERRITORY (e.g., en_US).

og:logo
string

The URL or identifier of the logo image of your website that will be displayed when your content is shared.

twitter:title
string

The title of your page as it should appear in a tweet.

twitter:description
string

The description of your page as it should appear in a tweet.

twitter:handle
string

The Twitter handle of the page creator or site.

twitter:image
string

The URL or identifier of the image that will be displayed in a tweet.

twitter:site
string

The name of your website as it should appear in a tweet.

twitter:url
string

The URL of your page.

twitter:card
string

The type of card to be used for sharing on Twitter. Options: summary, summary_large_image, app, player

noindex
boolean

If set to true, the page will not be indexed by search engines.

nofollow
boolean

If set to true, a search engine will not follow any links present on the page.