Skip to main content

Using a Theme

In this tutorial, you’ll learn how to use Gatsby themes by creating a new site using the official Gatsby blog theme.

Create a new site using the blog theme starter

Creating a site using a theme starter starts the same way as using a regular Gatsby starter:

gatsby new my-blog

Run the site

Creating a new site from the starter installed all of the blog theme’s dependencies for you. Next, run the site and see what you have:

cd my-blog
gatsby develop

Default screen when starting a project using gatsby blog starter

Replace your avatar

The blog theme starter ships with a solid gray image for the avatar. Add your own avatar by choosing the image you want, and overwriting the file located at /content/assets/avatar.png.

Update your site metadata

Customize the information on your site by replacing the site metadata in the gatsby-config.js file.

module.exports = {
plugins: [
resolve: "gatsby-theme-blog",
options: {},
// Customize your site metadata:
siteMetadata: {
title: "My Blog",
author: "Amberley Romo",
description: "A collection of my thoughts and writings.",
siteUrl: "",
social: [
name: "twitter",
url: "",
name: "github",
url: "",

Replace the content of the bio

When using Gatsby themes, you can take advantage of something called component shadowing.

The Gatsby blog theme package has a component that contains the content of the site author’s biography. The file path to that component (in the blog theme package, not your site) is gatsby-theme-blog/src/components/bio-content.js.

If you look at the file tree of your site, you’ll see it looks like this:

├── content
│ ├── assets
│ │ └── avatar.png
│ └── posts
│ ├── hello-world.mdx
│ └── my-second-post.mdx
├── src
│ └── gatsby-theme-blog
│ ├── components
│ │ └── bio-content.js
│ └── gatsby-plugin-theme-ui
│ └── colors.js
├── gatsby-config.js
└── package.json

In the src directory of the site, there’s a gatsby-theme-blog directory. Any file placed in that directory that corresponds to a file in the blog theme will completely shadow the theme.

💡 The name of the directory (here gatsby-theme-blog) must exactly mirror the name of the name of the published theme package, which in this case is gatsby-theme-blog.

Open up the bio-content.js file and make some content edits:

export default () => (
This is my updated bio.
<br />
It's shadowing the content from the theme.

At this point, you should have an updated avatar, updated site details, and an updated bio:

Screenshot of project with current tutorial edits

Add your own blog content

Now you can add your first blog post, and get rid of the demo content in the starter.

Create a new blog post

Create a new file in my-blog/content/posts. Name it whatever you’d like (with a .md or .mdx file extension), and add some content! Here’s an example:

title: My first post
date: 2019-07-03
This will be my very first post on this blog!

Delete the demo posts

Delete the two demo posts in the /content/posts directory:

  • my-blog/content/posts/hello-world.mdx
  • my-blog/content/posts/my-second-post.mdx

Restart the dev server, and you’ll see your updated blog content:

Screenshot of project with updated post content

Change the color theme

The blog theme ships with a default Gatsby purple theme, but you can override and customize the theming of your site to your heart’s content. In this tutorial, you’ll change a few colors.

Open up /src/gatsby-theme-blog/gatsby-plugin-theme-ui/colors.js, and uncomment the code in that file.

const blue60 = "#007acc"
const blue30 = "#66E0FF"
const blueGray = "#282c35"
export default merge({}, defaultThemeColors, {
text: blueGray,
primary: blue60,
heading: blueGray,
modes: {
dark: {
background: blueGray,
primary: blue30,
highlight: blue60,

Now, instead of a purple theme, you have a blue theme instead:

Screenshot of project with updated color theme

In this file, you’re pulling in the default color theme (imported as defaultThemeColors here), and overriding certain color keys.

To see what other theme colors you can customize, check out the colors.js file in the official blog theme (gatsby-theme-blog/src/gatsby-plugin-theme-ui/colors.js)

Wrapping up

This was a step-by-step introduction to using a Gatsby theme through looking at a specific example. Note that different themes will be built differently, to accept different customization options. To dive deeper, check out the Gatsby Theme docs.

Edit this page on GitHub