Getting Started with GatsbyJS and WordPress

Do you know how to create a static website with HTML, CSS, and JavaScript? I believe you have used WordPress once to create your own blog.

You can use WordPress, without knowing how to create your own themes and plugins. There are a lot in the wild. But then it starts to get complicated once you start tinkering on things the way you want it to.

What if there's a way to turn WordPress into an API or a data source in which you could pull content and display it anywhere?

In this post, we will be setting up WordPress in Headless mode, create a basic HTML/CSS template, and use GatsbyJS to integrate our template with WordPress.

WordPress

I will assume you know how to install WordPress. If not, here is a step by step guide.

To setup WordPress in Headless mode, we will need to install the following plugins:

• WP API Menus - This will expose the Menus as an API. The built-in WordPress API does not expose menus.
• Advanced Custom Fields - We would be able to create custom fields based on rules and be able to access it through an API
• Custom Post Type UI - Sometimes Pages and Posts are not enough, we would like to create custom posts like Products, Movies, etc.
• Postlight Headless Theme - This theme will remove the Webpages on the client-facing frontend and will replace it with JSON.

Running in Headless mode means we will still be using the WordPress Dashboard to manage content but we will be serving those through an API. Hence, we won't be using WordPress to show the generated content to our visitors.

Make sure you have at least 1 post and 1 page on your WordPress site. Make sure at least 1 post has at least 1 tag. We will be using this for the latter part.

HTML/CSS Template

Now that we have a WordPress setup. Let us start creating the base template of our website. I will be using the Holy Grail layout from this article at Alligator.io

Holy Grail is a layout pattern that’s very common on the web. It consists of a header, a main content area with fixed-width navigation on the left, content in the middle and a fixed-width sidebar on the right and then a footer.

Here is the demo I built on Codepen.io. We will be using this as our layout on GatsbyJS.

GatsbyJS

If you are following this guide, I assume you have NodeJS setup on your machine. If not, here is a step by step guide.

GatsbyJS is ReactJS under the hood so it would be easier to follow this if you have basic understanding of React or frontend frameworks in general. Here is a good starter to ReactJS Basics by Maximilian Schwarzmüller. Don't worry, you should still be able to follow this guide.

Setting up GatsbyJS

We will be using the gatsby-starter-wordpress. Here gatsbyhg is the name of our project, you may use any name you want.

GatsbyCentral / gatsby-starter-wordpress

LOOKING FOR MAINTAINER - - - A GatsbyJS starter template that leverages the WordPress API, ACF and more

Gatsby v2 WordPress Starter

This starter is forked from the gatsby-starter-netlify-cms and modified to use WordPress instead of netlify-cms, using the gatsby-source-wordpress plugin as the data connector.

Demo: https://gatsby-starter-wordpress.netlify.com/

Looking for maintainer: If you're interested in taking over the maintenance of this starter, please reach out in an issue. We're not working with Gatsby any more (it got way too complicated, hello nextjs), and so we're not maintaining this.

Use It Now

gatsby new NAME https://github.com/GatsbyCentral/gatsby-starter-wordpress

• Edit gatsby-config.js, change baseUrl
  • Make sure you have at least 1 post and 1 page on your WordPress site
  • Make sure at least 1 post has at least 1 tag
• Ensure the permalink structure in your WordPress installation is set to Post Name instead of the deafult Plain, or else the gatsby-source-wordpress plugin won't be able to communicate with WordPress
• Rejoice
  • For more information on the source plugin, check out the…

View on GitHub

npx gatsby new gatsbyhg https://github.com/GatsbyCentral/gatsby-starter-wordpress

You can preview what's on this gatsby starter template by running it

yarn start

Then, navigate to http://localhost:8000/

Connecting to our WordPress site

To connect to our WordPress site. Open the gatsby-config.js file. Look for baseUrl, modify it to point to your site without the https://. Start the project and check if the content displayed is indeed from your WordPress site.

yarn start

Integrating our HTML/CSS template

The gatsby-starter-wordpress already has a template built with it. We will replace this with our Holy Grail layout.

First, let's edit the src/components/Layout.js to match our layout.
We will be specifically modifying this portion:

 <div>
   <Helmet title="Home | Gatsby + WordPress" />
   <Navbar />
   <div>{children}</div>
 </div>

To this :

  <div className="layout">
    <Helmet title="Home | Gatsby + WordPress" />
    <header>Header</header>

    <Navbar />

    <main>{children}</main>

    <aside>Sidebar</aside>

    <footer>Footer</footer>
  </div>

Next we add a CSS file called style.css under src/components/ with the following content:

/* Layout */

.layout {
  display: grid;

  grid-template-areas:
    "header header header"
    "nav content side"
    "footer footer footer";

  grid-template-columns: 200px 1fr 200px;
  grid-template-rows: auto 1fr auto;
  grid-gap: 10px;

  height: 100vh;
}

header {
  grid-area: header;

  display: flex;
  justify-content: space-between;  
}

nav {
  grid-area: nav;
  margin-left: 0.5rem;
}

main {
  grid-area: content;
}

aside {
  grid-area: side;
  margin-right: 0.5rem;
}

footer {
  grid-area: footer;
}

/* Theme */
/* This is optional, you can use your own style for this */

body {
  padding: 0;
  margin: 0;
  font-family: -apple-system,system-ui,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;
}

header {
  font-size: 18px;
  color: #fff;
  min-height: 20px;
  background: #0a2b4e;
  padding: 20px;
}

nav,
aside {
  background: #666;
  padding: 10px;
  color: #fff;
}

footer {
  background: black;
  color: #fff;
  padding: 20px;
}

.navbar-item {
  display: inline-block;
  color: #fff;
  padding: 10px;
}

.navbar-item img {
  height: 20px;
}

.pagination {
  margin: 0;
  background: black;
}

.pagination a {
  color: #fff;
}

Modify style imports on src/components/Layout.js

import './style.css' // add this
import './style/all.sass' // remove this, we won't be needing this anymore

You can view the demo here. The source code is here.

Comments

[Renaud Kern]

Interesting article. But how the gatsby frontend is updated when there is new post on WP?

[Aivan Monceller]

I have explored this plugin to solve this. During save, this will call a build hook on Netlify to trigger the deployment.

Make sure you have something set for both Production and Staging, else the plugin will not work.