DEV Community

Phil Tietjen for Devplebs

Posted on • Updated on

Adding a Blog to the DevPlebs Site with Gatsby Themes - Part 1

Keith wanted to start writing dumb articles and with our website only having the podcast for content it seemed like a great time to add a gatsby blog theme to our gatsby site!

I thought it would be cool to document the process of doing this as on paper it's supposed to be quite a plug and play implementation, but we'll find that out together!

Where Do We Start?

Well since we have a site that already opinionated about its styling, let's try the gatsby-theme-blog straight from gatsby!

Install

yarn add gatsby-theme-blog

Configuration

Before we add our configuration, let's take a look at the configuration options we have available.

Key Default Description
basePath '/' The site path our blog lives at
contentPath '/content/posts' The file path our posts live at
assetPath '/content/assets' The file path our assets live at
mdx true To use MDX or not to render post markdown

Essentially, the base path is going to dictate where gatsby will create pages through the theme's gatsby-node file.

The contentPath and assetPath are fed through into the theme's gatsby-config file to configure the gatsby-source-plugin to know where to grab the data and throw it up to the GraphQL layer.

Since I have no opinions on any of these options other than where the posts live, I'll just configure the basePath to keep it simple.

// gatsby-config.js
...
{
  resolve: `gatsby-theme-blog`,
  options: {
    basePath: `/blog`,
  },
},
...

Now it's worth noting that at this point other than some additional configuration for metadata, this is the end of what the official gatsby-blog-theme tells us about using this theme. So it's time to wing it!

Using The Theme

Everything is set up so we should be ready to start using the theme.

Adding Some Content

During configuration, we left the assetPath and contentPath to its default values. We'll need to start by adding those folders the theme will be looking for at the root of the project.

mkdir content
cd content
mkdir posts
mkdir assets

As you can tell, I'm a professional at the command line 😎

File tree showing the new "content/assets" and "content/posts" directories

Now we can add a dummy post to test it out!

cd content/posts
touch first-post.mdx
---
title: First Post Dawg
published: false
---

# It's a brand new world!

For anyone not familiar, the content in between the hyphens (---) is known as frontmatter in markdown and contains key-value pairs, everything below it is the body.

Time to run the app and see what this looks like!
gatsby develop

Error log from gatsby's develop script about "Cannot return null for non-nullable field MdxBlogPost.date."

Aw Nuts

I guess the gatsby-theme-blog didn't like that we had a post with no date field. Well, we can fix this fairly easily.

---
title: First Post Dawg
date: 15-01-20
published: false
---

# It's a brand new world!

Now when we run gatsby develop it looks like everything is all good! πŸŽ‰πŸŽ‰πŸŽ‰

Before we continue, I think we should find out exactly what fields we have access to since that's probably important if we're going to use this theme. Since it wasn't included in the documentation for the theme, we'll have to go looking at the Gatsby source code.

To find the source code for the gatsby-theme-blog we have to go through some directories in the main repository starting with the packages directory.

Screenshot of Gatsby's GitHub repository with an arrow pointing to a "packages" directory

Here we can find the gatsby-theme-blog
Screenshot of Gatsby's Github repository nested under the "packages" directory with an arrow pointing to a "gatsby-theme-blog" directory

Strangely enough, there doesn't seem to be a gatsby-node file for this theme. This is important because that's where an API is provided for us by Gatsby to control data in the graphQL data layer. We can at least look into the gatsby-config file to see what's up.
Screenshot of Gatsby's Github repository nested under the "packages/gatsby-theme-blog" directory with a question mark and arrow

Aw nuts

Looking at the gatsby-config, it looks like gatsby-theme-blog uses another plugin called gatsby-theme-blog-core. I'm betting that's where the data stuff is!
Screenshot of Gatsby's Github repository nested under the "packages/gatsby-theme-blog/gatsby-config.js" file

Oh, look! There is the gatsby-theme-blog-core plugin right above the gatsby-theme-blog.
Screenshot of Gatsby's Github repository nested under the "packages" directory with an arrow pointing to a "gatsby-theme-blog-core" directory

Voila! We have found our gatsby-node file.
Screenshot of Gatsby's Github repository nested under the "packages/gatsby-theme-blog-core" directory with a question mark and arrow pointing to a "gatsby-node.js" file

Under packages/gatsby-theme-blog-core/gatsby-node.js is where we finally find what fields we have available to us!
Screenshot of Gatsby's Github repository nested under the "packages/gatsby-theme-blog-core/gatsby-node.js" file showing the node interface for a blog post's schema

Field Type
id String
title String
body String
slug String
date Date
tags String[]
keywords String[]
excerpt String

We could continue with our blog or I think this would be a good time to pause and consider that what we just did was a pretty flawed experience. We had to assume the shape of data for our posts from an installed theme we did not have prior knowledge of. Luckily for us, Gatsby is powered by the wonderful world of open source!

I added separate pull requests for their gatsby-theme-blog and gatsby-theme-blog-core packages to add a table of fields a blog post has to their README.md files.
Screenshot of Gatsby's submitted pull requests displaying 2 items assigned to the user "Phizzard"

πŸŽ‰πŸŽ‰πŸŽ‰ Yay for open source! πŸŽ‰πŸŽ‰πŸŽ‰

Before we get back on track I want to re-enforce that it was the lack of documentation that led us down this little rabbit hole, not the architecture of the gatsby-theme-blog packages. I think it was a great idea to separate the gatsby-theme-blog into a core and complete package that we'll get to benefit from!

Back on Track

To quickly recap, we installed the gatsby-theme-blog plugin, configured it, and created our first test post. So really we should be good to just go to the path we set the theme to install at which was at "/blog".

Screenshot of the website at "/blog" showing the gatsby-theme-blog working

πŸŽ‰πŸŽ‰πŸŽ‰ We have a blog! πŸŽ‰πŸŽ‰πŸŽ‰

One Problem Doe

Minus the extra stuff we did, installing the gatsby-theme-blog did a lot of the work for us in giving us the data, pages, and styling for including a fully functional blog on our site! However, in our case, there is now a serious disconnect in the way our site looks and this theme section so it's going to need a little extra work in our case to get things like our main navigation, header, footer, and overall look and feel onto the theme pages.

From here we have two options.

  1. Use component shadowing to override components the theme is using.
  2. Uninstall the gatsby-theme-blog and Install gatsby-theme-blog-core which just gives us the data without the frontend components.

SPOILER ALERT: I'm going to be going with option 2 for our final decision, but I want to explore attempting option 1 a little because component shadowing in gatsby with themes is very cool!

This is the end of part 1 and I hope you enjoyed this blend of documenting a realistic development process/tutorial?

Let me know what you think! Good or bad!
See you in part 2!

Cat crawling under cushions of a blue couch

Time For The Plug!

Friday Night Deploys Podcast by The Devplebs

We Have a Podcast!

Keith Brewster and Phil Tietjen are 2 Canadian Web Developers and friends who decided to start what may be best described as a web development-focused and personality-driven podcast show called "Friday Night Deploys". It's a weekly show aimed to release every Friday where we share our experiences and stories about related topics and we typically like to go off the rails here and there.

Where To Listen

Spotify: https://open.spotify.com/show/7oXdJ5aETg5GBSNC6jZSNq
Itunes: https://podcasts.apple.com/ca/podcast/friday-night-deploys/id1485252900
Google Play Music: https://play.google.com/music/m/I54hbbplhdmovo2so6cxsctkcaq?t=Friday_Night_Deploys
Our Website: https://devplebs.tech
PodBean: https://devplebs.podbean.com/

Where To Reach Us

Twitter: https://twitter.com/DevPlebs (DM's or Mentions welcome)
Email: deadbeats@devplebs.tech

We hope you have fun listening and to hear from you!

Top comments (2)

Collapse
 
laurieontech profile image
Laurie

You’re the source of the available README fields?! Best friend! Thanks so much for contributing. I’m working on even more updates surrounding documentation and agree with all of the stuff you’ve said thus far. Can’t wait for part 2!

Collapse
 
phizzard profile image
Phil Tietjen

I'm glad it went noticed and appreciated! I was more than happy to contribute to Gatsby (The project and team are all awesome!) and include the idea of running into a pain point and trying to resolve it when using an open-source project!

I hope to contribute to Gatsby more in the future and get part 2 out soon!

Also looking forward to the upcoming updates surrounding documentation! :D