Skip to main content

Using a Gatsby Theme

While you can get started quickly with a Gatsby theme starter, you can also install a Gatsby theme directly to an existing Gatsby site. Gatsby themes are plugins, so you can install and use them like any other Gatsby plugin.

Installing a Theme

Like any Gatsby plugin, Gatsby themes are Node.js packages, so you can install them like other published packages in Node using npm or yarn, including local workspaces.

For example, gatsby-theme-blog is the official Gatsby theme for creating a blog.

To install it, run in the root of your site:

npm install --save gatsby-theme-blog

Theme options

Depending on the theme, there may be theme options that can be configured via gatsby-config.js.

For example, gatsby-theme-blog can take in 4 potential options: basePath, contentPath, assetPath, and mdx. These options are also documented in the theme’s README file.

gatsby-config.js
module.exports = {
plugins: [
{
resolve: `gatsby-theme-blog`,
options: {
/*
- basePath defaults to `/`
- contentPath defaults to `content/posts`
- assetPath defaults to `content/assets`
- mdx defaults to `true`
*/
basePath: `/blog`,
contentPath: `content/blogPosts`,
assetPath: `content/blogAssets`,
mdx: false,
},
},
],
}

To learn how to further customize a theme, check out the docs on Gatsby theme shadowing.

Published Themes

Public Gatsby themes are published on npm for anyone to use. You can also publish private themes for use by your organization. Examples of private theme package hosting include the npm registry and GitHub Package Registry.

Using Yarn Workspaces

If you would like to work with unpublished themes, consider setting up Yarn Workspaces for theme development and using Yarn instead of npm.


Edit this page on GitHub
Docs
Tutorials
Plugins
Blog
Showcase