Using Gatsby Theme Options Part 2

Previously in the series

This is the third post in a series about getting started with Gatsby themes where we learn about themes progressively. In the first blog post, we set up a Gatsby website from scratch, and added the gatsby-theme-blog, which takes some Markdown or Mdx content in a specified folder, transforms it into pages on our website, and gives us some nice base components and styles.

In the second post, we discussed what options are in themes, how to customize the theme with the options available, and where to look inside of the theme to find what options are available as well as how those options are used.

If you haven't read from the beginning of the series Using Your First Gatsby Theme, you might want to before continuing.

What are we going to discuss today?

In this post, we are going to customize our Gatsby website by changing some of the options available to us from gatsby-theme-blog.

In the next post we'll discuss what shadowing is as a concept in Gatsby, and how to find the things that can be shadowed in a theme.

If you'd like to see the completed code for this section, check the branch Using Gatsby Theme Options Pt 2 on Github.

Changing the base URL of our blog

Right now our blog index, the page rendering a list of our blog posts, is rendering at our root path "/", but what if we want to add a blog to an existing website, or what if we want to make something else our home page?

Luckily that's pretty easy to change.

If you remember, the gatsby-theme-blog has a few options that we can change. One of them is a property called basePath. This basePath determines the base URL for our blog content. The default is /, but let's go ahead and change that to /blog.

Open up gatsby-config.js

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

What this will do is make the blog index render at '/blog' and make the blog posts render at '/blog/:slug' where :slug is replaced with the slugified version of your title.

It's pretty common to call it slugifying when you set all characters to lowercase and change any characters that don't fall between a-z or 0-9 into "-".

Last time we changed our src/pages/index.js page to /src/pages/_index.js so that Gatsby wouldn't try to render our index page in place of our blog index. Now that we have the blog rendering at a different path, let's change the filename back to index.js.

mv src/pages/_index.js src/pages/index.js

We'll also want to add a navigation component so that we can get to our home and blog page.

Let's first make a components directory inside of the src directory. And then we'll make two new components, layout, and navigation.

mkdir src/components
touch src/components/{layout,navigation}.js

In my experience with Gatsby I always need a generic page layout, or maybe a few different layouts for different types of pages. You will sometimes see these living in src/templates or sometimes src/components. Either is perfectly fine, but I try to stick with keeping layouts that affect markup and styles in src/components, and use src/templates only for tying the data requirements for programmatic pages to a visual component or set of visual components.

// src/pages/index.js
import React from 'react'
import Layout from '../components/layout'

export default function HomePage() {
  return (
    <Layout>
      <h1>Welcome!</h1>
      <p>
        Hello, from Gatsby{" "}
        <span role="img" aria-label="hand emoji waving hello">
          👋
        </span>
      </p>
    </Layout>
  )
}

/////////////////////////////////////////
// src/components/layout.js

import React from 'react'
import Navigation from './navigation'

export default function Layout({ children }) {
  return (
    <>
     <Navigation />
      <main>
       {children}
      </main>
    </>
  )
}

/////////////////////////////////////////
// src/components/navigation.js

import React from 'react'
import { Link } from 'gatsby'

export default function Navigation() {
  return (
    <nav>
      <ul>
        <li><Link to="/">Home</Link></li>
        <li><Link to="/blog">Blog</Link></li>
      </ul>
    </nav>
  )
}

There are a few things to note when we start our Gatsby site up 1) it's really ugly, and 2) the navigation is on the home page but not the blog page :( bummer.

To fix problem one just use your favorite styling method whether that's CSS-in-JS, CSS modules, Sass, etc. I won't be touching the general styles because that is beyond the scope of this series. If you're interested in learning about different ways to style your Gatsby website let me know in the comments and I'll write an article.

To fix problem two we are going to have to learn how to shadow components. We'll discuss what shadowing is in the next post.

Next up

If you found this post useful and want to see more from this series leave a reaction or comment. I'm trying to find the right length and depth per article so please let me know if you think this length is too short

In the next post, we'll learn about what shadowing is, why it's so powerful, and how Gatsby resolves shadowed content.