The Ultimate [Free] Jamstack

Knox Lively
Mar 16, 2020 · 7 min read

Introduction

As an aspiring freelance writer, and newly published author (Achieving DevOps), I had a real need to set up a writing portfolio to showcase my work. I knew I needed a place to host my website, and a means by which to create it. There were a few criteria that my tech stack had to meet to satisfy my [picky] needs.

  1. All tools and services must be free
  2. To have the ability to write content in Markdown
  3. Lightweight, fast, and server-less
  4. Easy to use

After a bit of “light googling”, I stumbled upon GitHub Pages for my hosting solution. I’m not sure how after 10 years on GitHub I have just now found out about this service. Nonetheless, it sounded perfect for my needs. The concept was simple, all one had to do was to deploy their static website pages to a [very specifically named] GitHub repository, and your site is live. Easy peasy.

The second part I had to figure out was how to generate those pesky web files. I have a background in software development, but web development not so much. I simply didn’t have the time to hand write HTML, CSS, JavaScript, and whatever else the kids use these days. I simply wanted to write in Markdown. This led me down the path of exploring static site generators. After a bit of research it seemed that the easiest, most reliable, and quickest static site generator currently available [for me at least] was Hugo.

Lastly, I wanted the ability to manage my site with a Content Management System (CMS) platform that would enable me to focus on writing content, not building a website. When it came to CMS I also knew I didn’t need, or want the complicated overhead of a full-blown platform such as WordPress. Long story short, googling led to redditing and I ended up stumbling upon Forestry.io, a web-based [and free] CMS platform. The intention of this product is to be able to hand off an already mature website to an individual or team who prefers to use CMS to generate content, rather than having to build the site by hand as developers do.

With the tech stack defined lets get to building your free hosted, and cms-enabled website!

GitHub Pages + Hugo Setup

This first half is focused on getting your GitHub account, repositories, and your Hugo site up and running. In the next half we will focus on getting Forestry set up. Before we get started, make sure you have a GitHub account. It’s free, easy to set up, and arguably the worlds most popular software development platform.

  1. The first step is to create two repositories in GitHub.
<project-name>

This repository will host your Hugo website. Name it appropriately (e.g. blog/portfolio/etc). Secondly, lets create our GitHub Pages repository.

<your_github_username>.github.io

This is the repository that will host the public files from your Hugo site. (Note: This repository MUST be named using this exact format in order to use GitHub Pages.)

2. The next step is to install Hugo (Linux and Windows users can follow this guide.)

brew install hugo

3. Now we are going to create a bare bones Hugo site.

hugo new site portfolio

4. Before we go any further lets get this site into your project repository so we can get it under version control. We’ll do this by first checking out your project repository you created earlier.

git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>

And then copying the contents from the site you just created (“portfolio” in this example) into this repository.

cp -r * /path/to/portfolio .

5. Now for the fun part, lets add a theme to your new Hugo site. I recommend themes.gohubo.io as a good starting place for finding themes.

In the root of your project repository run the following commands:

git initgit submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

You’ll notice that this particular method of adding a theme is done by using a git sub-module. It is slightly more complicated than adding a static directory into the themes folder of your site, however this will enable you to update your theme more easily in the future.

(Note: Simply run git pull inside your themes folder to update it)

6. This step is optional, but highly recommended. We are going to populate our new website with the configuration file, as well as some content, from the theme we just installed. This will allow us to see the site as it was seen on the demo, and is easier for those newer to Hugo and static site generators in general.

cp themes/ananke/config.toml .cp themes/ananke/content/* content

7. Now lets create our first post. This will create a skeleton post in the content directory where you can begin writing your first post.

hugo new posts/my-first-post.md

8. Lets get your server up and running and see this beautiful site!

hugo server

9. I’m sure its a gorgeous site, now lets figure out how to deploy this puppy and see it on the world wide web. Our next step will be getting you set up to deploy this new website to your GitHub Pages repository for hosting.

First, stop your local Hugo server.

Ctrl+C

Next we want to remove the public directory from the project repository.

[You’ll see why in the next step]

rm -rf public

We now need to add the other repository you created earlier as a sub-module to this repository.

git submodule add -b master https://github.com/<USERNAME>/<USERNAME>.github.io.git public

When you run the hugo command from this point forward, it will build your site and put it in the public directory within your project. The public directory will now have a different remote origin, which is your GitHub Pages repository we created in Step 1. This allows us to serve only the static files of your project from that repository.

Lastly, in order to generate the static pages for your site you can simply run:

hugo

It’s that simple! But lets take it one step further and automate this deployment process using a very simple deploy script. That way once you’ve committed your project repository all you have to do is run this simple script to get your site committed to Git, then deployed to your GitHub Pages account.

Save the following script to a filename of your liking. I chose to name mine, deploy.sh

Ensure the script is executable, then run it.

chmod +x deploy.sh./deploy.sh

That’s all there is to getting your Hugo development environment set up and to deploying your website. In the meantime I recommend reading through the Hugo documentation. You’ll want to familiarize yourself with a lot more concepts than what we’ve covered in this tutorial to build your perfect website.

Forestry.io Setup

Congrats on getting through the hard part! Now the easy part is adding our CMS to our website. Before we get started head on over to Forestry.io and create your account. It’s free for personal use and allows you to add up to 3 users per website.

  1. In the top right-hand corner of the page, click “Add Site”, then simply select “Hugo” as your static site generator.

2. Chose your Git provider to connect Forestry to your repository host.

3. A browser window [not pictured] should then pop up asking for your credentials in order to authenticate. After authentication simply select the repository that contains your project, NOT the one we use for GitHub Pages that contains your username.

4. You will then be prompted to pick a branch. If it works as it should, Forestry will detect your configuration file [config.toml]. (Note: If it fails then make sure Hugo is properly set up.)

That is it! You now have a free, GitHub Pages hosted website using Hugo and Forestry.io as your CMS. Just remember, that any changes you make using Forestry will auto-commit to your project repository, so don’t forget to git pull once you’re done editing your site content with Forestry.

Conclusion

I hope you have as much fun as I did setting up this simple, and free, jamstack. Best of luck to you and building your new website. I’m sure there’s a thing or two I missed, or ways I could improve this work flow. Please feel free to comment below if you can make this post better in any way. Thanks and please do check back in from time to time as I post new content regularly.

The Startup

Get smarter at building your thing. Join The Startup’s +794K followers.

Sign up for Top 10 Stories

By The Startup

Get smarter at building your thing. Subscribe to receive The Startup's top 10 most read stories — delivered straight into your inbox, once a week. Take a look.

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Knox Lively

Written by

Writer | Speaker | Recovering Software Engineer. For my books and more, visit knoxlively.com.

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +794K followers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store