SITE NAME CHANGE: Hi there, this is just a quick note to explain why the site name seems to have changed. I've decided that my personal domain of Gecko8 wasn't nearly descriptive enough. I want to cover not just code, but how to make our lives better as developers. With that goal in mind, I feel Life And Code is a better choice. I hope you agree!

This article is part three in an ongoing series on creating a blog site similar to this one. It covers the initial steps in setting up the Gridsome framework and adding in the NetlifyCMS blog settings. In Part 4 I'll cover building the actual display of the blog list and individual posts!

_For Part 2 which covers the framework decisions for the project, see Framework choices.

Welcome to Part 3 in my series on building and hosting a static website based on Vue for free! So far we've just been talking about how I got to this point. In this section we're going to start building the Gridsome and NetlifyCMS portions of the project.

First, A Couple Quick Notes

GraphQL

I won't be going into a lot of detail on GraphQL and honestly, I'm far from an expert. I personally don't find it to be the most intuitive language but it does seem to be gaining a lot of traction in the industry and does provide some really nice flexibility in accessing data. You can find more information on their site at https://graphql.org.

Markdown

Markdown is a popular markup language for writing content. You'll see it used extensively on sites like Github and others. I've personally started using it to keep notes, etc. and it's really well suited to writing blog posts. Here's a useful guide if you want to learn more about it. https://www.markdownguide.org.

Yarn or NPM

This is one of those ongoing debates in the industry. My opinion? Use whichever you're used to. There's not a dramatic difference between the two anymore so why learn something new?

Setup GIT Repository

As mentioned in the earlier posts in the series, NetlifyCMS is centered around the use of GIT for storing your content. In our case, we'll be using the same repository as our site code but you could just as easily store your content in a separate repository with different access permissions, etc.

I'm not actually going to go into the details of setting up a GIT repository and gaining access for pushing, committing, etc. as there are several providers available and the processes are all slightly different. Not to mention you can access GIT in a couple of different ways (SSH or HTTP). Perhaps I'll write another post about that in the future. For this post, we'll just assume you have a repository setup on one of the three main providers: GitHub, GitLab, or BitBucket. These are all well supported by NetlifyCMS. Here's the links to the main documentation for each:

• GitHub: https://help.github.com
• GitLab: https://about.gitlab.com/get-started
• BitBucket: https://confluence.atlassian.com/bitbucket/bitbucket-cloud-documentation

If you're looking for an opinion on which to use, I've used all of them a fair amount and they're actually all pretty good. GitHub's pricing used to be more restrictive around private repositories but even that has changed recently. They all have generous free plans now.

Install Gridsome

We'll need the Gridsome CLI to create and work on our project so let's get that installed. Open your terminal (or console) of choice and enter the following command.

yarn global add @gridsome/cli

or

npm install -g @gridsome/cli 

Create Your Gridsome Project

The Gridsome CLI does a good job of creating a straight-forward starting project so we won't be creating one from scratch. I know, I usually don't like it when tutorials go "run this command and we're done!" but in this case the project is pretty simple so I'll just settle for describing things after we create it.

In your terminal, navigate to where you would like to create your project. I tend to have a GIT folder somewhere where I keep all my GIT repositories but that's just personal preference. Enter the command:

gridsome create gridsome-blog

When it's done, enter

cd gridsome-blog

And let's see if it works

gridsome develop

You should see a bunch of output ending with something like:

  Site running at:                                         
  - Local:                 http://localhost:8080/          
  - Network:               http://<your internal network ip>:8080/         
                                                           
  Explore GraphQL data at: http://localhost:8080/___explore

Open that url and you should see a typical Gridsome template site

Quick Tip : You can easily open a url from the terminal on a Mac by holding down the command key and double-clicking the link (single click in iTerm2)

Great, we now have our basic Gridsome site!

Add to GIT Repository

Let's quickly commit it to our GIT repository before we go on. We'll do this from the command-line but you can easily use your favorite GIT GUI (I like SourceTree).

First, let's create the local GIT repository. At the root of your project folder, enter:

git init

Now, let's commit our changes to it.

git add .
git commit -m "Initial commit"

Now, add our external repository as a remote.

git remote add origin <your repository url>

And finally, push our changes to the remote repository master branch

git push origin master

We now have our code in our GIT repository, ready to continue.

Project Structure

As I promised earlier, we'll now take a look at what the Gridsome CLI created. Open up the gridsome-blog folder created by the CLI in your favorite editor. Mine is Visual Studio Code but that really doesn't matter. The directory structure should look like this:

Here's a quick description of each piece.

• .cache: Internal Gridsome build stuff
• node_modules: I probably don't need to describe this but it's where npm or yarn installs dependencies
• src: Where you’re site pages, etc. live
• static: Where files you want copied directly to your site during build are. For example, robots.txt, host config data like .htaccess or web.config files, etc.
• gridsome.config.js: Contains Gridsome plugin configuration
• gridsome.server.js: Provides the ability to hook into the Gridsome API itself. You likely won’t need this for this project.
• package.json: Typical npm file listing all dependencies and other project stuff.
• yarn.lock or package-lock.json: Dependency management file used by yarn or npm.

See, like I said earlier, it's pretty straight-forward. If you're used to normal Vue, React, etc. projects with Webpack, etc. this may seem like a breath of fresh air. It's so simple because Gridsome will be building everything into static files before deployment so there's no need for all the features of something like Webpack.

Add NetlifyCMS

First we need to add a few dependencies. Run the following command in your terminal:

yarn add netlify-cms gridsome-plugin-netlify-cms @gridsome/source-filesystem @gridsome/transformer-remark

Here's what the dependencies do:

• netlify-cms: Core NetlifyCMS library
• gridsome-plugin-netlify-cms: Simplifies configuration of NetlifyCMS in Gridsome
• @gridsome/source-filesystem: Provides access to filesystem files via GraphQL
• @gridsome/transformer-remark: Provides access to Markdown syntax

Setup the Plugins

Open up the gridsome.config.js file in your editor. Let's add the following item to the plugins array:

{
  use: '@gridsome/source-filesystem',
  options: {
    path: 'blog/posts/**/*.md',
    typeName: 'Post'
  }
}

• path: Tells Gridsome where to look for the NetlifyCMS Markdown blog post.
• typeName: Defines how we’ll reference the posts in the GraphQL.

Now add the following to the plugins array:

{
  use: `gridsome-plugin-netlify-cms`,
  options: {
    publicPath: `/admin`
  }
}

• publicPath: Tells Gridsome what url to use to allow access to the admin backend. This is where you’ll go to create blogs, etc. For example, if you’re blog is hosted at https://crazylifeandcodethoughts.com, the admin portal would be at https://crazylifeandcodethoughts.com/admin.

That's it for the plugins. It's a lot, but we're getting there! Here's what the gridsome.config.js file should look like when you're done.

// This is where project configuration and plugin options are located. 
// Learn more: https://gridsome.org/docs/config

// Changes here require a server restart.
// To restart press CTRL + C in terminal and run `gridsome develop`

module.exports = {
  siteName: 'Gridsome',
  plugins: [    
    {
      use: '@gridsome/source-filesystem',
      options: {
        path: 'blog/posts/**/*.md',
        typeName: 'Post'
      }
    },
    {
      use: `gridsome-plugin-netlify-cms`,
      options: {
        publicPath: `/admin`
      }
    }
  ]
}

Setup NetlifyCMS

Go ahead and create a blog folder at the root of your project. Inside it, add posts and uploads sub-folders.

NOTE : This is a bit different structure than what you’ll see in the official Gridsome docs. I just prefer to keep all blog content together.

Create an admin folder in the src folder. In the admin folder, create an index.html file with the following content:

<!doctype html>
<html>
<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Gridsome Blog</title>
</head>
<body>
 <script src="index.js" type="module"></script>
</body>
</html>

Feel free to change the title to whatever you want! There’s nothing remarkable here, it’s just the placeholder html for the NetlifyCMS backend.

Add an index.js file to the admin folder with the following content

import CMS from ‘netlify-cms’

Yeah, that’s really all that goes in there.

Add a config.yml file to the admin folder. As you can see from the extension, this is a YAML file. I won’t get into the details of YAML here but the structure is pretty simple. Properties are represented by and indented : pair. Array elements are represented by an indented - .

Here’s the basic content.

backend:
  name: github
  repo: your_account_name/repo_name
 
media_folder: "blog/uploads"
public_folder: "/uploads"
 
collections:
 - name: "posts"
   label: "Posts"
   folder: "source/blog"
   create: true
   slug: "{{slug}}"
   fields:
     - {label: "Title", name: "title", widget: "string"}
     - {label: "Title Color", name: "title_color", widget: "string"}
     - {label: "Banner", name: "banner", widget: "image"}
     - {label: "Author", name: "author", widget: "string"}
     - {label: "Publish Date", name: "date", widget: "date"}
     - {label: "Body", name: "body", widget: "markdown"}
     - {label: "Summary", name: "summary", widget: "string"}
     - {label: "Keywords", name: "keywords", widget: "list"}

Here's a brief rundown on what the first few bits do.

• backend: Contains the GIT provider you’re using and the repo name. For example, name is likely one of github, gitlab, or bitbucket. An important note here is that by default, NetlifyCMS will commit any new posts and uploads to the main repository branch (e.g. master). If you want to post to a different branch, specify the branch property on backend with the branch name as the value.
• media_folder: Folder in the GIT repo where uploaded files (images, etc.) will be saved. public_folder: The path that will be used to access the uploaded files. For example, if you uploaded an image called apple.png, it would be saved as blog/uploads/apple.png in your repository and could be accessed from https://crazylifeandcodethoughts.com/uploads/apple.png.

IMPORTANT: Make sure you have the / character at the beginning of the public_folder property.

Collections

This is where most of the interesting stuff happens. Here you define the information about your blog posts, which is really why we’re doing this! collections is an array of the different types of posts you have. That’s right, you can have different types for anything you want. Say you want to use NetlifyCMS to manage the content for your site pages? Define a “page” type and go for it. Maybe you want to add a portfolio section? Define a “portfolio” type and you’re set! You’re really only limited by your imagination. We’re going to focus on the boring old blog post though.

For each collection we have several options.

• name: unique id for the type
• label (defaults to name): title of the type in the NetlifyCMS admin portal.
• folder: specifies where our blog posts are stored.
• create: specifies whether new items can be created.
• slug: specifies how post slugs (short name) are formatted. Using {{slug}} tells NetlifyCMS to use the data field name “title” to use an _ delimited version of the title. This is similar to what you see in most Wordpress blogs, etc.
• fields: this defines the various data fields in each post. The fields we’re creating here are just what I’ve found to work well for my blog (so far), so feel free to customize!

package.json Scripts

That’s the basic setup of our blog site but before we try it out, let’s make our life a bit easier. Open the package.json file at the root of your project. Change the scripts section to this:

 "scripts": {
   "build": "gridsome build",
   "develop": "gridsome develop",
   "explore": "gridsome explore"
 },

Save Your Work!

Save your work and let's commit our changes to GIT with the commands:

git add .
git commit -m "Setup NetlifyCMS"
git push origin master

Test it Out

Yay! We've reached the moment of truth! Well, the first of several anyway. Run the following to start the project in development preview.

yarn develop

or

npm run develop

Does it build and start the server? Yes, great! No? Hmm, it should. Once it’s running, open the site in the browser as we did before. It should look exactly the same. But wait, where’s my blog? Remember, this is a static site, not Wordpress. We have to build the pages to display the blog list and the blogs themselves. But don’t worry, we’ll get to that in the next post! But let’s start with creating a post so there will be something to display.

• Adding Your First Blog Post

Navigate to the admin portal for your site (likely http://localhost:8080/admin). Depending on how you setup GIT access, this may log in automatically. If not, enter your username and password for your GIT provider.

You should now see something like

I won’t go into a lot of detail here but the Posts page is where you’ll edit your blog posts and the Media page is where you can manage all uploaded images, etc. This is very similar to how other blog frameworks work. Let’s hit that New Posts button!

You should see the new blog post form. Feel free to add whatever content you want.

Once you have the form filled out, click the Publish button and choose Publish Now. That’s it!

NOTE: I want to interject here to say that this is what I really love about NetlifyCMS. It provides a very similar experience to other blogging platforms so you could actually hand this url over to your company marketing people. They could then add blog posts without knowing anything about GIT, Vue, or any of the other development details.

Okay, let’s see what it did. In your terminal or GIT client, pull the latest changes to your dev machine. The command likely looks something like this.

git pull origin master

In your editor, open the blog/uploads folder. You should see the image file you uploaded for the banner image. Even cooler, open the blog/posts folder and you should see an .md file for your blog (mine is called test-blog-1.md)!

Let’s open it up and take a look. It should look something like this:

---
title: Test Blog 1
title_color: '#abcdef'
banner: /uploads/site-construction.png
author: Jason Lewis
date: 2019-10-05T17:00:29.044Z
summary: My first post
keywords:
 - a
 - b
 - c
---
Woah, this is my first amazing blog! Hmm, maybe I should add some real content before posting it...

That’s all there is to it. The area between the --- lines are the various properties we defined. After the last --- is our Markdown formatted content.

A cool side effect of storing the posts in GIT in such a manageable format is that you could bypass the admin portal all together and just create your blogs directly in your code editor. As long as your post file and image files are in the correct directories, when you commit to your repository they’ll immediately be available.

That’s it for this post. As you can see, we now have all of our code and content living in a single GIT repository. This makes it really easy to hit the free requirement we specified earlier! See you in the next post where we’ll build the display of the blog list and posts.