When quarantine began in March, I decided that this extra time spent at home was a good opportunity to start writing articles and tutorials around things I know and have been learning.
I didn't have a personal website, so I wanted to quickly put something together to host my articles and tutorials.
I also did not want to pay for it. š
I began researching an implementation. The site needed to be simple to deploy and update, have a back-end content management system, and have a flexible front-end that I could easily build and style.
After a little research I landed on my solution: Netlify CMS with continuous deployment, Gatsby on the client side, with GitHub as my source-of-truth.
If you'd like to look at the final site, take a peak over here.
How the site works is that it uses Netlify CMS, which is a headless content management system (CMS) to manage the data (such as blog posts). This data can then be queried and displayed by a front-end static site generator like Gatsby, which uses React ā¤ļø . In order for the Gatsby Front End to retrieve the data it needs from the Netlify CMS, it uses GraphQL, a query language.
A headless CMS means, literally, cutting the head from the body; the head being the front end, the body being the backend or database. Unlike Wordpress, which has a database, admin interface, read/write integration, and a front end, a headless CMS has only one focus: storing and delivering structured content.
It is a content repository that makes content accessible via a RESTful API for display on any device.
Now for the front-end: Gatsby.
I love React. React is what allowed me to break into the industry as a self-taught developer and has continued to provide me with value in the marketplace. Since Gatsby is React, and the two communicate using GraphQL, it was a perfect fit.
Lastly, Netlify CMS uses Git as it's source of truth for continuous deployment. This means that every time you make a change to your code locally and push the updated code to your Git repository, Netlify see's this change and runs a new build of your site.
If the build fails, then the deployment exits and the broken code does not effect your live site.
Effortless continuous deployment, simple to set up, and free.
Let's walk through this together.
Deploy to Netlify
for the Gatsby Site Starter.Site deploy in progress
and watching the deploy progress.So, assuming you want your site to have a real website name of your choosing, you'll have to purchase one. You can do that from domain providers like Bluehost or GoDaddy, or simple buy it from Netlify like I did. The site and cms is free, the domain can never be free. Well, at least not a good one.
Thankfully, to deploy and customize this site you do not need to buy a domain name. For now, let's proceed to pulling this code down locally.
With this demo site connected to our Github account, it's time that we pulled the code down locally and explored it a bit.
Go to your Github Repositories, open the repository that was created using the name in step 3 (ie gatsby-starter-netlify-cms
), and copy the repo link.
Now open your command line / terminal, navigate to where you want your project to exist locally (ie. Desktop, Documents), and pull the repo down with git clone [your-repo-name]
> cd Desktop
> git clone https://github.com/marshallmurphy/gatsby-starter-netlify-cms-demo.git
Next, change directories into your project, install the dependencies, and launch the app locally.
> cd cd gatsby-starter-netlify-cms-demo
> npm install
> netlify dev
Let the site build until you see a confirmation that you can now view the site locally at localhost:8000
, and confirm it is indeed up and running by visiting that location in your browser.
Great! We are now ready to mess around with this starter template and customize it as we see fit.
What I mean by using Github as the source-of-truth is the fact that Netlify CMS, since it is tied to that Github repo you created in step 3, will trigger a new build of the site whenever the code in the repo changes.
In fact, all of your static assets like images, and even your markdown blog posts, will live as files in your repository.
Let's look at an example.
Open the site locally at localhost:8000
and navigate to a blog post (here's one for example). You can find all of the content for each individual blog post in src/pages/blog
.
It's all written in markdown, which results in a static html page.
Additionally, all images in various posts can be found in static/img
.
It's as simple as that.
Now if you look at src/components/BlogRoll
and scroll to the bottom, you will see the default GraphQL query for the blog roll, which is the blog page that shows all posts with their titles, date, tags, etc.
This is the basic structure of how components and templates are retrieving data. A component with a query executes the query on mount, populating the page accordingly.
Take some time to poke through it. You'll notice that the frontmatter
values correlate with the values at the top of a blog post.
---
templateKey: blog-post
title: A beginnersā guide to brewing with Chemex
date: 2017-01-04T15:04:10.000Z
featuredpost: false
featuredimage: /img/chemex.jpg
description: Brewing with a Chemex probably seems like a complicated, time-consuming ordeal, but once you get used to the process, it becomes a soothing ritual that's worth the effort every time.
tags:
- brewing
- chemex
---
You can explore and refine your queries with Graphiql at localhost:8000/___graphiql
.
For example, executing the BlogRoll query:
That's basically it.
Now it's up to you to fiddle around with the code to craft it into the site that you desire.
For me, I simply wanted a site to display all of my posts by date as tiles on the website's home page, and then have each post be viewable. All that this required was to move the BlogRoll query into the home page.
A major selling point for me when researching this implementation was that blog posts were written in markdown. When I write, I use Typora to write in markdown, and so this was a perfect fit for me.
To style this site I removed Bulma entirely, created a flexible tile component, wrote a few helper utility functions for the homepage layout, and created the CSS in all.scss
to match the design that I quickly whipped together in Sketch.
All in, maybe 4-5 hours of work?
Not bad, considering the site is Free (minus the domain name), responsive, and uses continuous deployment,
And since this is not something I wanted to devote much time to, I'll take it.