Rebuilding my website with Gatsby and Contentful

As mentioned above, this GIF was is small walk through of what my website looked like, very basic, how I like it. I was going to keep the design simple, just some contact details and then my blogs. I have used Gatsby a few times before, so am somewhat familiar with it.

Gatsby is site generator (could be static or dynamic). The primary technologies users interact with are React and GraphQL. Under the hood, there are many things the user doesn't have to deal with or set up (webpack). The build process and the websites are very quick. I believe the big ecosystem is also a plus, with many plugins and the ability to source data from many different systems. The community is also great, many members of Gatsby are very friendly and willing to help, there is a lot of documentation available as well.

To get started, I created my new website project by running the below command:

gatsby new YOURPROJECTNAMEHERE

I had Gatsby installed globally, can be installed by running:

npm install -g gatsby-cli

To get the local development environment started, run the below (make sure you're in the right directory) and go to localhost:8000

gatsby develop

I chose to start with the beginner, basic Gatsby project. The files can be found here: https://github.com/gatsbyjs/gatsby-starter-default

Here is the file structure locally. Most of my work is done in the src/ directory as well as gatsby-config.js and gatsby-node.js files.

Browsing through the files within the src/ directory, you will find most files contain some sort of React component and possibly a GraphQL query.

src/components/layout.js

That is a small overview of what a Gatsby project comes with. Let's switch gears to talk about the data and where it'll be coming from.

Contentful

Contentful among other services, is a content management system (CMS). I am using it to create blog posts. After creating an account, you can set up your content model (short texts, long texts, media, different types of data).

Here is what my blog post content model will feature -

Once you set up your content model, you can maybe create some content (like a test blog post) just so you know its working once you connect it to your Gatsby app. The next step is to connect it to your web app.

gatsby-source-contentful is the package/plugin needed. You can find full documentation on what it is and how to use it here: https://www.gatsbyjs.org/packages/gatsby-source-contentful/

Once installed, you can connect your Contentful account by entering the spaceId and Access Token into your gatsby-config.js file as seen below.

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-contentful`,
      options: {
        spaceId: `your_space_id`,
        // Learn about environment variables: https://gatsby.dev/env-              vars
        accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
      },
    },
  ],
}

As seen in code comment, please check out https://gatsby.dev/env-vars for how to set up environment variables so your accessToken isn't public and pushed onto your Github repository.

Once your environment variables are set up, you can now familiarize yourself with GraphQL and the GraphiQL playground. This is a helpful tool to query your data. Here is the Gatsby documentation on GraphiQL.

On the left, under the explorer, is all the information you can run a query for. On my index.js page, I want to have a list of all my blogs, so I ran the below query.

The query is on the left, the results are on the right. I wanted to retrieve the titles, id's, and slugs of all the blog posts I've created on the Contentful CMS. On the right, you can see only that data is returned.

The next step(s) are to create a file which will house the blog post, a template. I created a template folder within the src directory, and created the file blogPost.js. It will contain a query and also a React component.

Once all done, it looks like this.

We will come back to the blog template but we can start to work on the gatsby-node.js file. Gatsby Node APIs are pretty powerful and you can do a lot, can read up on them here. We will be using the createPages API since we want to create blog posts on individual pages.

The documentation is very helpful as it provides an example of createPages we can amend a little to fit into our project.

The example uses 'allMarkdownRemark' where we have our 'allContentfulBlogPost'. We provide the slug data to create the individual blog post url. We are providing the blog post template, running the query, then taking the results, using forEach to goes through all the results, running createPage on each result.

If this is done successfully, you can test it out by going to each individual blog post page, and see if the slug has been created. All the content may not be there if the blog template was not set up yet.

Back to the blog post template, our query will look a little different as we need to use contentfulBlogPost instead of allContentfulBlogPost. The template is for an individual blog, not all (as the index page will contain the list of all blogs). This is what we want/need to query onto our blogPost.js template. The slug argument is 'eq' equal to the slug from the path name.

One other important thing is the use of childMarkdownRemark, from the plugin gatsby-transformer-remark. The blog posts from Contentful are in markdown, this plugin transforms markdown to html, which is what we query.

From here, it seems just about done. On my index page, I see the two (test) blog posts I published.

And here is a a blog post page. From the query, we requested title, content, tags, date, which is all displayed on this page.