How to start using a Gatsby theme when you are already using gatsby-blog-starter?

February 10th, 2020

GatsbyJS

Lots of developers use gatsby-starter-blog, the most popular blog starter, as a boilerplate for their blogs. Since then, Gatsby themes were introduced and it reduces a lot of boilerplate. The main idea is that you can use a generic theme and override its configuration and components (it's called shadowing).

In this article, we will assume that you created a blog with the gatsby-starter-blog and want to switch to the gatsby-theme-blog to:

reduce the boilerplate code in your project
keep your project up to date easily (gatsby-starter-blog feels like the eject mode of Create React App)
maybe extend your website in the future by adding other themes (we won't dive into it in this post as it is covered in the official documentation)

This article describes how I changed my personal blog from a starter to a theme and I hope this will be useful to you!

Creating a new project with gatsby-starter-blog-theme

I would recommend that you start by creating a new project with this command:

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

It is based on a starter using gatsby-theme-blog.

Note that you can also just add a theme to your existing project with yarn add gatsby-theme-blog and move things around. A Gatsby theme is just plugin!

Copy your content to the new project's content folder

In content/assets/, the generic name for the profile image in the bio component is avatar.png. So if you didn't change the boilerplate that much I would advice that you give the same name as the theme.

The folder content/blog/ becomes content/posts/! Just pastes your articles in the new folder. Don't worry about the eventual custom fields you added in the posts markdown files. We will see about shadowing in the next part.

Shadow the components you did modify in the boilerplate

Gatsby themes allow you to overwright some of the theme components. It's called shadowing.

To shadow a component from the gatsby-theme-blog you have to modify it in src/gatsby-theme-blog/components/. There is an example with the <Bio/> component in the official documentation.

Start by doing a diff (using meld for example or your favorite diff tool) of your previous project src/components/ files with the files from the same folder from an unmodified gatsby-starter-blog.

Then just add the modified files in the new project's src/gatsby-theme-blog/components/ folder to shadow the components from the theme.

Adding plugins

If you have added plugins to your previous projects, be aware that some things changed from the starter to the theme. Here is my gatsby-config.js

module.exports = {
    plugins: [
        {
            resolve: `gatsby-theme-blog`,
            options: {},
        },
        `gatsby-plugin-sitemap`,
        {
            // This part is taken from the gatsby-theme-blog-core: https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-theme-blog-core/gatsby-config.js
            resolve: `gatsby-plugin-mdx`,
            options: {
                extensions: [`.mdx`, `.md`],
                gatsbyRemarkPlugins: [
                    {
                        resolve: `gatsby-remark-images`,
                        options: {
                            // should this be configurable by the end-user?
                            maxWidth: 1380,
                            linkImagesToOriginal: false,
                        },
                    },
                    { resolve: `gatsby-remark-copy-linked-files` },
                    { resolve: `gatsby-remark-smartypants` },
                    { resolve: `gatsby-remark-external-links` }, // adding a custom gatsby-remark plugin here
                ],
            },
        },
    // other plugins
    ]
}

gatsby-plugin-mdx seems to be used instead of gatsby-transformer-remark in the starter. I don't know how extending plugins work for the moment. Maybe it's not necessary to repeat all the options in this file. I'll update the article once I find out.

Handling favicon with gatsby-plugin-manifest

One of the features that seem to be missing from the theme but was in the starter is the manifest. It allows you to add a favicon for example.

Add the plugin with yarn add gatsby-plugin-manifest and paste your configuration in the gatsby-config.js. Here is mine:

        // in plugins:
        {
            resolve: `gatsby-plugin-manifest`,
            options: {
                name: `vincentdnl.com`,
                short_name: `vincentdnl`,
                start_url: `/`,
                background_color: `#ffffff`,
                theme_color: `#663399`,
                display: `minimal-ui`,
                icon: `content/assets/favicon.png`,
            },
        },
        // other plugins

Then copy your previous favicon png file to content/assets/favicon.png.

Edit your siteMetadata

This is pretty straightforward. Just copy your previous siteMetadata from your previous site to the new projects gatsby-config.js.

Conclusion

Your new project can now be deployed. It should work like the previous one except that it is much more easier to update (the gatsby-theme-blog plugin will be updated by the people maintaining it) and you have less code in your repository (only your own code, the one you modified from the starter).

Note that you also gained a dark/light theme switch button on top of your site. Developers reading your blog will love it! 🎉