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 😎
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
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.
Here we can find the gatsby-theme-blog
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.
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!
Oh, look! There is the gatsby-theme-blog-core plugin right above the gatsby-theme-blog.
Voila! We have found our gatsby-node file.
Under packages/gatsby-theme-blog-core/gatsby-node.js is where we finally find what fields we have available to us!
| 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.
🎉🎉🎉 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".
🎉🎉🎉 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.
- Use component shadowing to override components the theme is using.
- Uninstall the
gatsby-theme-blogand Installgatsby-theme-blog-corewhich 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!
Time For The Plug!
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)
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!
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