Using Multiple Themes Together

What this tutorial covers

This tutorial covers how to compose multiple themes into a final site using gatsby-theme-blog, gatsby-theme-notes and gatsby-mdx-embed as examples. It will also cover the concept of component shadowing with Theme-UI for styling.

Prerequisites

This tutorial assumes the following:

That you have an understanding of Gatsby fundamentals
An existing knowledge of Gatsby Themes

Example repository

You can view a full working example of this tutorial on GitHub. Some longer code snippets have been edited for length and the full code is available for reference in the example repository.

Create a new site

Using the hello world starter create a new site and navigate to that directory.

Install and compose the themes

This step composes gatsby-theme-blog and gatsby-theme-notes.

Install the themes:

Edit gatsby-config.js to add the themes to the plugin array and to update the site metadata:

Run the site:

Checkout http://localhost:8000 to see what is currently there.

Add content

Behind the scenes, the two themes created content folders in the root directory of the site. In this step, you will add some content to these folders.

Add a post

Create a new file in /content/posts, like this one:

Add a note

Create a new file in /content/notes, like this one:

Restart your development server with gatsby develop. Now if you visit http://localhost:8000/blog/hello-posts/ and http://localhost:8000/notes/hello-notes you should see your new content.

Add an avatar image

Put an avatar image into the content/assets/ directory, this is used by gatsby-theme-blog for the bio component. The file name can be avatar.png or avatar.jpg.

Put the blog posts on the homepage

Delete the existing src/pages/index.js file.
Change the theme options for the blog theme in gatsby-config.js:

Restart your development server with gatsby develop to test your new homepage.

Shadow components

Use theme shadowing to customize components the theme provides for you.

Shadow `bio-content.js`

The first component to update is bio-content.js which provides the content used in the gatsby-theme-blog bio component.

💡 Don’t forget to stop and restart your development server when adding a shadowed component for the first time.

In order to shadow the file, you need to place it in the same location it exists within the theme. In this case, that means src/gatsby-theme-blog/components/bio-content.js. So you’ll create a file structure that looks like this:

Feel free to make the text of your bio anything you like, but the component will look something like this:

Shadow Theme UI

gatsby-theme-blog and gatsby-theme-notes both use Theme-UI design tokens to manage their styling: colors, font sizes, spacing, etc. You can use component shadowing to gain control over these design tokens in the final site.

As with your bio, you need to match the file structure of the theme. In this case, that’s src/gatsby-plugin-theme-ui/index.js and the resulting structure will look like this:

Feel free to use whatever colors you like, but here is an example of what you could do.

Note that this example uses deepmerge. This allows you to use the Theme-UI configuration for any settings you don’t override in this file.

Add another theme

Themes can be big, like gatsby-theme-blog, but they can also be a small discrete set of components or functions. A great example of this is gatsby-mdx-embed which adds the ability to embed social media content and videos directly into your MDX files.

Install the theme:

Update the gatsby-config.js file and add gatsby-mdx-embed as a plugin:

Test it out by adding a YouTube video to one of your blog posts:

Use component shadowing to add a navigation menu. You can read more about creating dynamic navigation menus in the docs.

Add a menuLinks array to gatsby-config.js:

Create the navigation component:

When that is done the next step is to shadow header.js from gatsby-theme-blog. You can copy and paste code from the original component as a starting point for your new shadowed component.

Your file structure should look like this:

src/gatsby-theme-blog/components/header.js

Import the navigation menu and add it to the header:

💡 This code snippet is edited for length the full component can be viewed on GitHub.

Run gatsby develop and test the new navigation component.

Wrapping up

This tutorial has introduced you to the idea of composing multiple themes together in a single Gatsby site. Gatsby Themes are an innovative rethink of the traditional website template and understanding their potential gives you a powerful new set of tools as a developer. To keep diving deeper, check out the Gatsby Theme docs and some of the other resources listed below.

What’s next?

Building a theme

Other resources

Edit this page on GitHub