This article was originally published at codebushi.com

Gatsby Theme Document Demo ( view source )

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 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.

Installing a Gatsby Theme

Using the Gatsby CLI

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/ First, let's look at the gatsby-config.js file.

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

<!-- 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 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

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.

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.

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.

Gatsby Theme Document Demo ( view source )