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.
- All tools and services must be free
- To have the ability to write content in Markdown
- Lightweight, fast, and server-less
- 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.
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.
- The first step is to create two repositories in GitHub.
This repository will host your Hugo website. Name it appropriately (e.g. blog/portfolio/etc). Secondly, lets create our GitHub Pages repository.
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!
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.
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:
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.
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.
- 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.
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.