Skip to main content
Official Plugin
View plugin on GitHub
See starters using this

Gatsby

The Gatsby Blog theme

A Gatsby theme for creating a blog.

Installation

For a new site

If you’re creating a new site and want to use the blog theme, you can use the blog theme starter. This will generate a new site that pre-configures use of the blog theme.

gatsby new my-themed-blog https://github.com/gatsbyjs/gatsby-starter-blog-theme

For an existing site

If you already have a site you’d like to add the blog theme to, you can manually configure it.

  1. Install the blog theme
npm install gatsby-theme-blog
  1. Add the configuration to your gatsby-config.js file
// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-theme-blog`,
      options: {
        // basePath defaults to `/`
        basePath: `/blog`,
      },
    },
  ],
}
  1. Add blog posts to your site by creating md or mdx files inside /content/posts.

    Note that if you’ve changed the default contentPath in the configuration, you’ll want to add your markdown files in the directory specified by that path.

  2. Run your site using gatsby develop and navigate to your blog posts. If you used the above configuration, your URL will be http://localhost:8000/blog

Usage

Theme options

Key Default value Description
basePath / Root url for all blog posts
contentPath content/posts Location of blog posts
assetPath content/assets Location of assets
mdxOtherwiseConfigured false Set this flag true if gatsby-plugin-mdx is already configured for your site.

Example configuration

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-theme-blog`,
      options: {
        // basePath defaults to `/`
        basePath: `/blog`,
      },
    },
  ],
}

Additional configuration

In addition to the theme options, there are a handful of items you can customize via the siteMetadata object in your site’s gatsby-config.js

// gatsby-config.js
module.exports = {
  siteMetadata: {
    // Used for the site title and SEO
    title: `My Blog Title`,
    // Used to provide alt text for your avatar
    author: `My Name`,
    // Used for SEO
    description: `My site description...`,
    // Used for social links in the root footer
    social: [
      {
        name: `Twitter`,
        url: `https://twitter.com/gatsbyjs`,
      },
      {
        name: `GitHub`,
        url: `https://github.com/gatsbyjs`,
      },
    ],
  },
}

Blog Post Fields

The following are the defined blog post fields based on the node interface in the schema

Field Type
id String
title String
body String
slug String
date Date
tags String[]
keywords String[]
excerpt String

Edit this page on GitHub
Docs
Tutorials
Plugins
Blog
Showcase