Gatsby.js Themes Introduction
Tags: react, gatsby, javascript, tutorial
Published: 2019-09-21 21:48:20

---
title: Gatsby.js Themes Introduction
published: true
description: Take a closer look at what makes up a Gatsby theme, how to use them, and what makes them different from a Gatsby Starter
tags: react.js, gatsby, javascript, tutorial
cover_image: https://thepracticaldev.s3.amazonaws.com/i/1kezwx9u1707xbm9fz50.jpg
canonical_url: https://codebushi.com/gatsbyjs-themes-introduction/
---

*This article was originally published at [codebushi.com](https://codebushi.com/gatsbyjs-themes-introduction/)*

<p class="mt-4 mb-4"><a href="https://gatsby-theme-document.netlify.com/">Gatsby Theme Document Demo</a> <small>( <a href="https://github.com/codebushi/gatsby-theme-document-example">view source</a> )</small></p>

When making a Gatsby.js site, there are two main ways to start. You could start from scratch by just installing `gatsby` `react` and `react-dom`. Then, based on what your needs are, you would add in various Gatsby plugins and other npm packages for your project.

Another, quicker, way is to use a Gatsby Starter. A Gatsby Starter is essentially boilerplate code and npm packages for a particular type of site or application. If you want to create a blog, for example, there is a [Gatsby Starter Blog](<[https://github.com/gatsbyjs/gatsby-starter-blog](https://github.com/gatsbyjs/gatsby-starter-blog)>) that has all the required plugins and packages you need, already configured in the `package.json` and `gatsby-config.js` files. All you do is clone the starter, make your modifications, and write articles using markdown files.

The problem with a Gatsby Starter is that once a user clones and changes the initial code, it becomes its own entity. The new codebase is branched off from the original starter code. If there was a bug fix or new feature for the starter, there isn't a good way to update the code for existing users of the starter.

Gatsby Themes were created to solve this problem. A Gatsby Theme is essentially a starter that has been made into a npm package. It can be easily updated just like any other package, and is used like a Gatsby plugin in the `gatsby-config.js` file. Let's try using the theme [Gatsby Theme Document](https://github.com/codebushi/gatsby-theme-document).

## Installing a Gatsby Theme

Using the Gatsby CLI

```bash
gatsby new document-site https://github.com/codebushi/gatsby-theme-document-example
cd document-site
gatsby develop
```

The site should be up at [http://localhost:8000/](http://localhost:8000/) First, let's look at the `gatsby-config.js` file.

```javascript
module.exports = {
  siteMetadata: {
    title: `Document by Code Bushi`,
    name: `Code Bushi`,
    siteUrl: `https://gatsby-theme-document.netlify.com`,
    description: `This is my description that will be used in the meta tags and important for search results`,
    social: [
      {
        name: `github`,
        url: `https://github.com/codebushi/gatsby-theme-document`
      },
      {
        name: `twitter`,
        url: `https://twitter.com/HuntaroSan`
      }
    ],
    sidebarConfig: {
      forcedNavOrder: ['/introduction', '/codeblock'],
      ignoreIndex: true
    }
  },
  plugins: [{ resolve: `gatsby-theme-document` }]
};
```

Notice at the very bottom, the `plugins` array contains the theme `gatsby-theme-document`. This is how we tell Gatsby to use a particular theme. If there are additional options for a theme, you would add it here as well. In this case, there are options for the theme are in the `siteMetadata`, like the social media links and `sidebarConfig`.

It's important to note that this repository is not the original repo for the actual theme. It's an example repo that has already been pre-configured with `gatsby-theme-document` in the `package.json` and `gatsby-config.js`. If we crack open the `/src` directory, we can see there are a few folders and files already here. These are also provided by the example repo so we know which files should be "shadowed" to use the theme properly.

### Component Shadowing in Gatsby Themes

With Gatsby Themes, files in the original theme's `/src` directory can be shadowed, or overwritten, by the Gatsby site that is using the theme. If you've ever worked with "child themes" before in Wordpress, this is a similar concept.

Looking at the theme example site we installed we can see a logo file in `/src/gatsby-theme-document/logo.mdx`. Any changes we make to this file will overwrite the original logo file from the theme, which can be found at `node_modules/gatsby-theme-document/src/logo.mdx`.

This is how we can customize a Gatsby theme and still have access to bug fixes or new features in the future. Open up the logo file in `/src/gatsby-theme-document/logo.mdx` and make a change

```md
<!-- Document -->

YOUR LOGO
```

You might need to refresh the page, but your site's logo should now be updated!

In fact, any file that is in the `node_modules/gatsby-theme-document/src` directory can be copied and "shadowed" in our current site. If you want to completely change the `Header` or `Layout`, simply copy those components out of the `node_modules/gatsby-theme-document/src/components` folder and into your `/src/gatsby-theme-document/components` folder to shadow it.

Next, we can take a look at the `colors.js` file in `/src/gatsby-plugin-theme-ui/colors.js`. This particular theme was built using Theme UI, and this `colors.js` file corresponds to the [Color Modes feature](<[https://theme-ui.com/color-modes](https://theme-ui.com/color-modes)>) from Theme UI. This is another shadowed file from the original theme, so we can overwrite the original colors by editing this file. Try changing the `background` color for the dark mode to `#000`

```javascript
modes: {
    dark: {
      text: "#fff",
      background: "#000",
      primary: "#f638dc",
      secondary: "#ff7976",
      sidebar: "#101d3c",
      borderColor: "rgba(255, 255, 255, 0.15)"
    },
```

If you go back to the site, you'll notice that change take place. You can edit or add additional color modes to this `colors.js` file and the theme will automatically recognize these changes. The color toggle icon that's in the top right corner of the site's header will allow you to cycle between each color mode.

### Writing Content With MDX

Now that we've looked at how to customize our theme, we can actually begin adding content to the site. If we look at the example content files under `/content`, you'll notice these are `.mdx` files. This theme uses MDX instead of traditional markdown files, which allows you to include React components as well as write JSX in your content files. You can read more about the benefits of MDX from their [website](https://mdxjs.com/).

You can simply edit or add to the existing mdx files in the `/content` folder to populate pages on the site. Since these pages are created dynamically by Gatsby, you may need to reload the page before seeing the new pages show up in the navigation.

To manually set which pages appear in what order in the navigation, you can open up the `gatsby-config.js` file and edit the `forcedNavOrder` array setting.

```javascript
sidebarConfig: {
  forcedNavOrder: ["/introduction", "/codeblock"],
  ignoreIndex: true
}
```

That wraps up this quick intro to Gatsby Themes. Hopefully this post has inspired you to try using a theme for your next Gatsby site and has given you some insight on how to customize a theme. Each theme is built differently, so read the documentation for the theme you're using to get it set up properly.

<p class="mt-4 mb-4"><a href="https://gatsby-theme-document.netlify.com/">Gatsby Theme Document Demo</a> <small>( <a href="https://github.com/codebushi/gatsby-theme-document-example">view source</a> )</small></p>