How to start a Gatsby project using a Gatsby Manor theme

You are going to start a gatsby (v2) project using a Gatsby Manor theme to quickly style your project website.

Start a new project

Use the gatsby-cli to create a new project in your desired directory. (If you don't have gatsby installed, use yarn global add gatsby-cli to install gatsby globally.)

gatsby new themes-starter https://github.com/gatsbyjs/gatsby-starter-default\#v2
cd themes-starter

Run gatsby develop and open a new window to see your test website. (Open your site using incognito mode, to prevent the browser from saving the gatsby builds.) Time to add a theme.

Add the gatsby themes helper library

By default, gatsby does not support theming, so we need a helper library. You want to install gatsby-themes-kit to add theme support to your project. The package allows you to use the themes found on Gatsby Manor.

yarn global add gatsby-themes-kit

Note: This packages is a wrapper around the gatsby-cli. The wrapper logic is used to add a little more logic to the gatsby-cli.

Setting up a new theme

First you will install a theme, then you will initialize a new gatsby-themes.yaml config to manage the themes for your project. Once the master config is created, view the theme in your browser (using incognito mode to prevent caching issues).

gtk init
gtk get gatsbymanor/gatsby-theme-identity
gtk set gatsby-theme-identity
gtk develop

Here you installed the theme nameed gatsby-theme-identity in the themes folder from the github repo gatsbymanor/gatsby-theme-identity.

Build your gatsby project using the theme

You have a theme, now you need to apply it to your gatsby project. First you will need to build the target theme, then copy over the build to the main project.

gtk build
gtk copy
gatsby serve

Open a browser window using incognito mode and visit http://localhost:9000 to see your newly build project with a ready made theme. Next we will explore how to bring your data to the theme template.

Data binding in your templates

To understand how to add data to our theme template we need to analyze the gatsby-themes.yaml file. You will use this file to add your source plugins and write the graphql queries you want loaded into the template theme. Then you can access the data via props.

Working with queries is exactly what you would do in the gatsby-config.js file of a normal gatsby project. All gatsby-themes-kit does is centralize your data sources, and loads them into your templates so you can use the same data with any template. Check themes/gatsby-theme-identity/gatsby-config.js and themes/gatsby-theme-identity/gatsby-node.js to see what gtk in your templates.

---
version: 1
themesDir: themes
theme: gatsby-theme-identity
data: >
  {
    site {
      siteMetadata {
        title
      }
    }
  }

In this file we specify the project directory where the themes are located using themesDir. The theme key is used to specify the default theme for the project. To provide data to your theme template, you need to add a data key. In the data object you provide write your graphql query. Then you can access the data via the props in your components.

class Index extends React.Component {

  render() {

    return (
      <div>
        {this.props.pageContext.data.site.siteMetadata.title}
      </div>
    )
  }
}

Using the contentful plugin

You will need to update your gatsby-themes.yaml with the data source plugins you want access to, in this case its gatsby-source-contentful. The syntax is similar to how you would specify it in the gatsby-config.js file. The example below queries the Bio entity in my demo contentful account.

---
version: 1
themesDir: themes
theme: gatsby-theme-identity
plugins:
  - resolve: gatsby-source-contentful
    options:
      spaceId: process.env.CONTENTFUL_SPACE_ID
      accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN
data: >
  {
    site {
      siteMetadata {
        title
      }
    }

    contentfulBio {
      name
      displayName
      headline
      photo {
        sizes(maxWidth: 120, quality: 95) {
          src
        }
      }
    }

  }

With your config file completed its time to develop and build the project, remembering to supply the access keys via environment variables. You don't have to install the plugin because gatsby-themes-kit takes care of adding any missing plugins using yarn. (Note: we need to work on a clean up solution.)

CONTENTFUL_SPACE_ID=YOUR_SPACE_ID CONTENTFUL_DELIVERY_TOKEN=YOUR_TOKEN gtk develop
CONTENTFUL_SPACE_ID=YOUR_SPACE_ID CONTENTFUL_DELIVERY_TOKEN=YOUR_TOKEN gtk build

Hi Steven,

(First reactions!)

I like the demo a lot. You've put some great work into this!! Super helpful.

I'm new to React and very new to Gatsby -- with your demo I'm able to see a viable way to achieve some important goals. I think the Gatsby community also needs to figure our a viable way to enable theming.

The gastby-theme-identity is really well done. Your rendition is a perfect match to the HTML5 Up original. I will say this, however... a multi-page theme would show off your work better! Identity theme is single page, no scrolling, no interaction apart from the social icons. If you were to use Massively or Forty, your demo would show page navigation, CSS animations, the whole works! I love the HTML5Up stuff -- such beautiful design.
What features are missing? Hmm... It would be great to demonstrate multiple themes and a means of switching them in real time.
I know that's a long way from the current code -- I think. (Is it?) The reason for such a feature is to experiment with ways that multiple themes can exist in a single build. You're already thinking about it -- it seems -- in your comment above about the yaml configuration: " The theme key is used to specify the default theme for the project." The phrase "default theme" implies that it's not a constant...it's a variable and could be overridden or set programmatically.
I already have recommended your work to someone -- just yesterday! https://spectrum.chat/thread/3bae3ca6-ac1a-4aa2-8eb8-2b56df3823a1?m=MTUzNjMyNzA0MTI5Mw==
Other comments:

The gist is straight-forward and accurate to follow. Every step worked and at the end I had on my computer exactly what you described. (Though, I didn't do anything with the Contentful instruction...I'm not [yet] a user of Contentful.)
I'm also interested to do a diff between vanilla Gatsby repo and a repo with your work included. The exercise will help me learn … but isn't something the typical reader of your Gist will need.

Remarkable! Thanks for sharing. I'd love to know what you intend next and whether I can be useful.

nodox/00-gtk-demo.md