Skip to content

Instantly share code, notes, and snippets.

@nodox nodox/01-gtk-demo.md
Last active Sep 14, 2018

Embed
What would you like to do?
How use a Gatsby Manor theme

How to use different Gatsby Manor themes

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 gtk-demo https://github.com/gatsbyjs/gatsby-starter-default\#v2
cd gtk-demo

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.

Setting up a new themes

Add some themes in your themes folders. You are going to install a couple pre-made themes: Story, Parallelism, and Read Only

gtk get gatsbymanor/gatsby-theme-story --as story
gtk get gatsbymanor/gatsby-theme-parallelism --as parallelism
gtk get gatsbymanor/gatsby-theme-read-only --as read-only

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. Initialize the project to create the required gatsby-themes.yaml file.

yarn global add gatsby-themes-kit
gtk init

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

View your theme: Story

The gatsby-themes.yaml file controls what theme is enabled for the gatsby project. We can use gtk to edit the theme property to enable your Story theme.

gtk set story
gtk develop

Visit localhost:8000 to see the image below in your browser.

Note: The theme key needs a value that is equal to the name of theme in your themes directory folder. If the path does not exist you will get an error.

gatsby-theme-story

View your theme: Parallelism

Use gtk to edit the theme field in gatsby-themes.yaml with parallelism as the value to view the Parallelism theme.

gtk set parallelism
gtk develop

Visit localhost:8000 to see the image below in your browser.

gatsby-theme-parallelism

View your theme: Read Only

Use gtk to edit the theme field in gatsby-themes.yaml with read-only as the value to view the Read Only theme.

gtk set read-only
gtk develop

Visit localhost:8000 to see the image below in your browser.

gatsby-theme-read-only

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. The value found in the theme field is the target theme.

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. Incognito mode prevents caching by the gatsby-plugin-offline plugin.

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/read-only/gatsby-config.js and themes/read-only/gatsby-node.js to see what gtk in your templates.

---
version: 1
themesDir: themes
theme: read-only
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: read-only
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

How to leave feedback

You can leave feedback by answering these questions. The answer you give will help make sure we build a tool you can find useful. You can answer one, or all. Any feedback helps!

  • What do you think about the demo?
  • What types of themes do you want for you projects?
  • What features are missing, need improvement from the cli?
  • Would you recommend this demo to other people looking for easy to use gatsby compatible themes?
  • What other comments do you have?

For anything else, you can reach me at gatsbymanor@gmail.com

Peace,

Steven

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.