gatsby-plugin-next-seo

Gatsby Plugin SEO makes managing SEO easier in your Gatsby JS project. It fully supports server-side rendering (SSR) with site wide configuration available via the

gatsby-config.js

GatsbySeo

This codebase was initially forked from the brilliant next-seo project and is now maintained separately.

Table of Contents

• gatsby-plugin-next-seo
  • Table of Contents
  • Usage
  • Setup
  • Add Plugin to Gatsby Config
  • Add SEO to Page
    • A note on Twitter Tags
  • Default SEO Configuration in Gatsby Config
  • GatsbySeo Options
    • Title Template
    • No Index
    • dangerouslySetAllPagesToNoIndex
    • No Follow
    • dangerouslySetAllPagesToNoFollow
    • Twitter
    • facebook
    • Canonical URL
    • Alternate
    • HTML Attributes
    • Meta Tags
  • Open Graph
  • Open Graph Examples
    • Basic Example
    • Video Example
    • Article Example
    • Book Example
    • Profile Example
  • JSON-LD
  • Override
  • Article
  • News Article
  • Blog Post
  • Breadcrumb
  • Blog
  • Book
  • Speakable
  • FAQ
    • Question Interface
  • Course
  • Corporate Contact (Deprecated)
  • Local Business
  • Logo
  • Product
  • Social Profile (Deprecated)
  • JsonLd
  • API Docs
  • FAQ
  • Why did you choose

    gatsby-plugin-next-seo

    as the project name?
  • Contributors

Usage

GatsbySeo

gatsby-config.js

Setup

First, install the plugin and it's peer dependencies:

npm install --save gatsby-plugin-next-seo react-helmet-async

or

yarn add gatsby-plugin-next-seo react-helmet-async

react-helmet-async

React.Context

Add Plugin to Gatsby Config

Add the following configuration to your

gatsby-config.js

module.exports {
  // ...
  plugins: [
    // ...
    'gatsby-plugin-next-seo'
  ],
}

The plugin allows documented GatsbySeoPluginOptions to be set. See an example below.

Add SEO to Page

Then you need to import

GatsbySeo

Example with just title and description:

import React from 'react';
import { GatsbySeo } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
    
Simple Usage
  >
);

But

GatsbySeo

Typical page example:

import React, { FC } from 'react';
import { GatsbySeo } from 'gatsby-plugin-next-seo';

const Layout: FC = ({ children }) => (
  <>
    
    
{children}
  >
);

export default Layout;

A note on Twitter Tags

Twitter will read the

og:title

og:image

og:description

gatsby-plugin-next-seo

twitter:title

twitter:image

twitter:description

Some tools may report this an error. See Issue #14

Default SEO Configuration in Gatsby Config

GatsbySeo

To achieve this, you will need to add the properties to your

gatsby-config.js

Here is a typical example:

// gatsby-config.js

module.exports {
  plugins: [
    {
      resolve: 'gatsby-plugin-next-seo',
      options: {
        openGraph: {
          type: 'website',
          locale: 'en_IE',
          url: 'https://www.url.ie/',
          site_name: 'SiteName',
        },
        twitter: {
          handle: '@handle',
          site: '@site',
          cardType: 'summary_large_image',
        },
      },
    },
  ],
}

From now on all of your gatsby pages will have the defaults above applied.

GatsbySeo Options

| Property | Type | Description | | ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |

titleTemplate

title

language

noindex

nofollow

description

canonical

mobileAlternate.media

mobileAlternate.href

languageAlternates

{ hrefLang: string, href: string }

metaTags

twitter.cardType

summary

summary_large_image

app

player

twitter.site

twitter.handle

twitter:creator

facebook.appId

openGraph.url

openGraph.type

openGraph.title

openGraph.description

openGraph.images

openGraph.videos

openGraph.locale

openGraph.site_name

openGraph.profile.firstName

openGraph.profile.lastName

openGraph.profile.username

openGraph.profile.gender

openGraph.book.authors

openGraph.book.isbn

openGraph.book.releaseDate

openGraph.book.tags

openGraph.article.publishedTime

openGraph.article.modifiedTime

openGraph.article.expirationTime

openGraph.article.authors

openGraph.article.section

openGraph.article.tags

Title Template

Replaces

%s

title = 'This is my title';
titleTemplate = 'Gatsby SEO | %s';
// outputs: Gatsby SEO | This is my title

title = 'This is my title';
titleTemplate = '%s | Gatsby SEO';
// outputs: This is my title | Gatsby SEO

No Index

Setting this to

true

noindex,follow

nofollow

nofollow

nofollow

robots

googlebot

Note: The

noindex

nofollow

index,follow

gatsby-plugin-next-seo

Example No Index on a single page:

If you have a single page that you want no indexed you can achieve this by:

import React from 'react';
import { GatsbySeo } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
    
This page is no indexed
  >
);

/*


*/

dangerouslySetAllPagesToNoIndex

It has the prefix of

dangerously

noindex

noindex

index

noindex: false

No Follow

Setting this to

true

index,nofollow

noindex

noindex

noindex

robots

googlebot

Note: The

noindex

nofollow

index,follow

gatsby-plugin-next-seo

Example No Follow on a single page:

If you have a single page that you want no indexed you can achieve this by:

import React from 'react';
import { GatsbySeo } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
    
This page is not followed
  >
);

/*


*/

dangerouslySetAllPagesToNoFollow

It has the prefix of

dangerously

nofollow

nofollow

follow

nofollow: false

|

noindex

nofollow

meta

robots

googlebot

index,follow

index,follow

noindex,follow

noindex,follow

index,nofollow

index,nofollow

noindex,nofollow

Twitter

Twitter will read the

og:title

og:image

og:description

gatsby-plugin-next-seo

twitter:title

twitter:image

twitter:description

Some tools may report this an error. See Issue #14

facebook

facebook={{
  appId: 1234567890,
}}

Add this to your SEO config to include the fb:app_id meta if you need to enable Facebook insights for your site. Information regarding this can be found in facebook's documentation

Canonical URL

Add this on a page per page basis when you want to consolidate duplicate URLs.

canonical = 'https://www.canonical.ie/';

Alternate

This link relation is used to indicate a relation between a desktop and a mobile website to search engines.

Example:

mobileAlternate={{
  media: 'only screen and (max-width: 640px)',
  href: 'https://m.canonical.ie',
}}

languageAlternates={[
  {
    hrefLang: 'de-AT',
    href: 'https://www.canonical.ie/de',
  },
  {
    hrefLang: 'es',
    href: 'https://www.canonical.ie/es',
}
]}

HTML Attributes

Add html attributes to the html tag with the

htmlAttributes

Example:

htmlAttributes={{
  prefix: "og: https://ogp.me/ns#",
}}

Meta Tags

This allows you to add any other meta tags that are not covered in the

config

content

name

property

Example:

metaTags={[{
  property: 'dc:creator',
  content: 'Jane Doe'
}, {
  name: 'application-name',
  content: 'GatsbySeo'
}]}

Invalid Examples:

These are invalid as they contain

property

name

metaTags={[{
  property: 'dc:creator',
  name: 'dc:creator',
  content: 'Jane Doe'
}, {
  property: 'application-name',
  name: 'application-name',
  content: 'GatsbySeo'
}]}

Open Graph

For the full specification please check out the documentation.

Gatsby SEO currently supports:

• basic
• video
• article
• book
• profile

Open Graph Examples

Basic Example

import React from 'react';
import { GatsbySeo } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
    
Basic
  >
);

Video Example

Full info on http://ogp.me/

import React from 'react';
import { GatsbySeo } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
    
Video Page SEO
  >
);

Article Example

import React from 'react';
import { GatsbySeo } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
    
Article
  >
);

Book Example

import React from 'react';
import { GatsbySeo } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
    
Book
  >
);

Profile Example

import React from 'react';
import { GatsbySeo } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
    
Profile
  >
);

JSON-LD

Gatsby SEO has the ability to set JSON-LD a form of structured data. Structured data is a standardised format for providing information about a page and classifying the page content.

Google has excellent documentation on JSON-LD -> HERE

• Override
• Article
• News Article
• Blog Post
• Breadcrumb
• Blog
• Book
• Speakable
• Course
• FAQ
• Corporate Contact (Deprecated)
• Local Business
• Logo
• Product
• Social Profile (Deprecated)
• JsonLd

Override

Each (non-deprecated) JSON LD component provides a set of utility props to help you in the journey of setting up your your site for Search Engine Optimization and voice assistant support. However there are times when you will need more control, and for these situations there is an

overrides

The following example would add a

datePublished

const OverrideCourseJsonLd = () => (
  
);

Currently, when using TypeScript, you must provide an

@type

overrides

Article

import React from 'react';
import { ArticleJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
Article JSON-LD
    
  >
);

News Article

This is simply a fancy wrapper around the

Article

import React from 'react';
import { NewsArticleJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
News Article JSON-LD
    
  >
);

Blog Post

A utility component which wraps the

BlogPosting

import React from 'react';
import { BlogPostJsonLd } from 'gatsby-plugin-next-seo';
 *
export default () => (
  <>
    
Blog Post JSON-LD
    
  >
);

Breadcrumb

import React from 'react';
import { BreadcrumbJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
Breadcrumb JSON-LD
    
  >
);

Required properties

| Property | Info | | --------------------------- | -------------------------------------------------------------------------------------------------------- | |

itemListElements

itemListElements.position

itemListElements.name

itemListElements.item

Blog

Identifies the page as a blog and outlines the available posts.

import React from 'react';
import { BlogPostJsonLd } from 'gatsby-plugin-next-seo';
 *
export default () => (
  <>
    
Blog with several posts
    
  >
);

Book

The

Book

An example feed is shown below.

import React from 'react';
import { CourseJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
Book JSON-LD
    
  >
);

Speakable

The speakable schema.org property identifies sections within an article or webpage that are best suited for audio playback using text-to-speech (TTS).

Adding markup allows search engines and other applications to identify content to read aloud on voice assistant-enabled devices using TTS. Webpages with speakable structured data can use voice assistants to distribute the content through new channels and reach a wider base of users.

import React from 'react';
import { SpeakableJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
Speakable JSON-LD
    
  >
);

FAQ

A Frequently Asked Question (FAQ) page contains a list of questions and answers pertaining to a particular topic. Properly marked up FAQ pages may be eligible to have a rich result on Search and voice assistants.

import React from 'react';
import { FAQJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
<h1>What?</h1>
<p>Stand</p>

<h1>How?</h1>
<p>Effort</p>

<h1>Why?</h1>
<p>Peace</p>
  >
);

| Property | Type | Description | | -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------- | | questions | Question[] | An array of Question elements which comprise the list of answered questions that this FAQPage is about. |

Question Interface

The questions and answers for an FAQ Page.

| Property | Type | Description | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ----------------------------------------------------------------------------------------- | | answer | string | The answer to the question. There must be one answer per question. | | question | string | The full text of the question. For example, "How long does it take to process a refund?". |

Course

import React from 'react';
import { CourseJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
Course JSON-LD
    
  >
);

Corporate Contact (Deprecated)

See the documentation with the reason for deprecation.

import React from 'react';
import { CorporateContactJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
Corporate Contact JSON-LD
    
  >
);

Required properties

| Property | Info | | -------------------------- | ----------------------------------------------------------------------------------------------- | |

url

contactPoint

contactPoint.telephone

contactPoint.contactType

Technical Support

Recommended ContactPoint properties

| Property | Info | | -------------------------------- | ---------------------------------------------------------------------------------------------------------- | |

contactPoint.areaServed

String

Array

"US"

["US", "CA", "MX"]

contactPoint.availableLanguage

"English"

["English", "French"]

gecontactPointo.contactOption

"TollFree"

Local Business

Local business is supported with a sub-set of properties.

Required properties

| Property | Info | | ------------------------- | -------------------------------------------------------------------------- | |

@id

type

address

address.addressCountry

address.addressLocality

address.addressRegion

address.postalCode

address.streetAddress

name

Supported properties

| Property | Info | | --------------- | ----------------------------------------------------------------------------------- | |

description

geo

geo.latitude

geo.longitude

images

telephone

url

NOTE:

Images are required for most of the types that you can use for

LocalBusiness

Logo

import React from 'react';
import { LogoJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
Logo JSON-LD
    
  >
);

| Property | Info | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | |

url

logo

Product

import React from 'react';
import { ProductJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
Product JSON-LD
    
  >
);

Also available:

sku

gtin8

gtin13

gtin14

Valid values for

offers.itemCondition

• https://schema.org/DamagedCondition
• https://schema.org/NewCondition
• https://schema.org/RefurbishedCondition
• https://schema.org/UsedCondition

Valid values fro

offers.availability

• https://schema.org/Discontinued
• https://schema.org/InStock
• https://schema.org/InStoreOnly
• https://schema.org/LimitedAvailability
• https://schema.org/OnlineOnly
• https://schema.org/OutOfStock
• https://schema.org/PreOrder
• https://schema.org/PreSale
• https://schema.org/SoldOut

More info on the product data type can be found here.

Social Profile (Deprecated)

See the documentation with the reason for deprecation.

import React from 'react';
import { SocialProfileJsonLd } from 'gatsby-plugin-next-seo';

export default () => (
  <>
    
Social Profile JSON-LD
    
  >
);

Required properties

| Property | Info | | -------- | ----------------------------------------------------------------------------------------- | |

type

name

url

sameAs

Google Supported Social Profiles

• Facebook
• Twitter
• Google+
• Instagram
• YouTube
• LinkedIn
• Myspace
• Pinterest
• SoundCloud
• Tumblr

JsonLd

This is the base JSON component that allows you to create your own JSON LD components according to the spec.

Google Docs for Social Profile

API Docs

You can explore the api documentation here.

FAQ

Why did you choose

gatsby-plugin-next-seo

as the project name?

Unfortunately the better options gatsby-seo and gatsby-plugin-seo were already taken. As a result I've used gatsby-plugin-next-seo as a shout out to the original next-seo project from which this codebase has been forked.

Contributors

Thanks goes to these wonderful people (emoji key):

Ifiok Jr. 💻 📖

Harlley Oliveira 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!