Configure SEO metadata

When you want to customize how your pages appear in search results or social previews, you can set defaults at the site level or override them on individual pages.

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.

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, subtitle, or excerpt fields

Site-wide defaults

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

1
metadata:
2
  # Core metadata
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."
6
  og:url: "https://developer.squareup.com/docs"
7
  og:locale: "en_US"
8
  canonical-host: "developer.squareup.com"
9
10
  # Social image
11
  og:image: "https://developer.squareup.com/images/docs-social-card.png"
12
  og:image:width: 1200
13
  og:image:height: 630
14
  og:logo: "https://developer.squareup.com/images/square-logo.png"
15
16
  # Twitter / X
17
  twitter:title: "Square Developer Platform Documentation"
18
  twitter:description: "Integrate payments, point-of-sale, inventory, and financial services into your applications with Square's developer platform."
19
  twitter:handle: "@SquareDev"
20
  twitter:image: "https://developer.squareup.com/images/twitter-card.png"
21
  twitter:site: "@Square"
22
  twitter:card: "summary_large_image"

Core metadata

Identity and descriptive fields used by search engines and shared across social platforms. Keep titles between 50–60 characters and descriptions between 150–160 characters for optimal display. Set canonical-host if your docs are accessible at multiple URLs (e.g., a custom domain and a buildwithfern.com subdomain) to tell search engines which URL is authoritative.

Social image

The image displayed when your docs are shared on LinkedIn, Slack, Discord, and other platforms. Use a 1200x630px image for the best display across platforms — this is the standard Open Graph size and will render correctly in most previews. Avoid embedding text in the image since it may be cropped on some platforms.

Dynamic OG images Beta

Instead of using a single static image for all pages, you can enable dynamic OG image generation. When enabled, Fern automatically generates a unique og:image for each page that doesn’t have one set in frontmatter.

You can optionally provide a custom background image (og:background-image) for dynamically generated OG images.

1
metadata:
2
  og:dynamic: true
3
  og:background-image: ./images/og-background.png # optional

Twitter / X

Controls how your docs appear in Twitter Card previews when shared on X.

Page-level overrides

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

1
---
2
title: PlantStore API Quick Start
3
headline: "Get Started with PlantStore API | Developer Documentation"
4
keywords: plants, garden, nursery
5
canonical-url: https://docs.plantstore.dev/welcome
6
og:image: https://plantstore.dev/images/api-docs-banner.png
7
og:image:width: 1200
8
og:image:height: 630
9
twitter:card: summary_large_image
10
twitter:site: "@PlantStoreAPI"
11
noindex: false
12
nofollow: false
13
---

Basic metadata

Page title, URL, and keyword fields used by search engines. Use headline when you need a different title for search engines than what appears as the visible page heading.

Open Graph

Controls how this page appears when shared on LinkedIn, Slack, Discord, and other platforms that support Open Graph. Keep titles between 50–60 characters and descriptions between 150–160 characters for optimal display.

Twitter / X

Controls how this page appears in Twitter Card previews when shared on X.

Indexing

Control whether search engines index this page or follow its links. These are distinct: noindex removes the page from search results entirely, while nofollow keeps the page in results but tells search engines not to pass ranking credit through its links.

Use noindex for internal-only pages, staging content, or pages you don’t want surfaced in search. You can also combine noindex with hidden: true in docs.yml to hide a page from both search engines and the sidebar — see Hiding content for details. Use nofollow sparingly — it’s rarely needed for documentation.