Using Forestry To Maintain Your Hugo Site on GitHub Pages

helena ✨ — Sun, 02 Dec 2018 14:48:39 +0000

There's a lot going on here. But let's make this as painless as possible.

Assumptions: You are using Hugo to generate a static site, which in turn is hosted on GitHub Pages. You then want to maintain future content using Forestry, a lightweight and beautiful CMS for Hugo/Jekyll meant for people who prefer to manage their content outside of a terminal.

Forestry is also free for personal use, which means they're perfect for individual bloggers. On the free tier, you can also collaborate with up to 3 guests.

Setup GitHub Pages & Hugo

My setup between Hugo and GitHub pages is based on this guide by @dgavlock, you can use the same guide to setup two seperate repositories that will power your site.

your-hugo-site: A repo for the 'backend' of Hugo. You will use this repo to configure your blog settings, add new posts, etc. This will be the repo you connect to Forestry.
<your-user-name>.github.io: This repo is for static files generated by Hugo. Forestry will deploy the files under public in the repo above to this one.

Create A Site on Forestry

Let's add a new site. In our case, pick Hugo (make sure you get the version correct. You can check using hugo version on your terminal):
Pick your git provider. Since your page is being hosted on GitHub pages, it'll be GitHub:
You'll be directed to GitHub for authentication, then you can pick which repo you would like Forestry to access. Pick the your-hugo-site repo you just created:

You'll be prompted to pick a branch, in our case it's master. If all goes well, Forestry will be able to detect your config.toml file. If it fails, you'll have to make sure your Hugo site is properly set up.
You'll be prompted to invite guests in the last dialog. Feel free to invite collaborators or skip that for now.
And there you go! You have connected your repo to Forestry. You can now access your posts through Forestry's UI.

Configuring Forestry

Once you're in the app, go to Settings to configure your Forestry and make sure it's deploying to the correct place.

Under General

Make sure you enter your url.
You can also turn on Deploy on Git Push if you fancy (it means pushing to your-hugo-site, not <your-user-name>.github.io). This means content will be deployed automatically to <your-user-name>.github.io if you push manually from the terminal.

Under Deployment

In Connection, pick GitHub Pages.
You'll be prompted to pick a repo from your GitHub account, in this case pick <your-user-name>.github.io. This will let Forestry deploy Hugo's changes under public/ to this repo.

If you're using a custom domain (ref)

Since Forestry overwrites your repo every time it deploys, you'll want to create a CNAME record under the static folder in your-hugo-site repo. Hugo will make sure a copy of your CNAME be deployed in the root directory.

From the root of your-hugo-site:

echo "your-url-here.com" > static/CNAME

Of course, you'll want to push those changes to your remote:

git add static/CNAME
git commit -m "Modify custom domain for my site"
git push origin master

Writing Blog Posts with Forestry

Forestry has a pretty Markdown editor that reminds me of Bear writer 🐻 It looks like this:

If You Want To Make Changes To Your Theme

You may want to change your blog's theme from time to time. In order to do that, you'll need to update the files under themes/ in your-hugo-site.

Head to <your-user-name>.github.io and make sure you've got the latest deploy from Forestry:

git pull origin master

Then, switch over to your-hugo-site and modify your theme.

Once you're done, get Hugo to generate the static files in your <your-user-name>.github.io:

hugo -D ../<your-user-name>.github.io

-D is a flag that allows you to define the destination for the generated static files.

Switch back to <your-user-name>.github.io and push the changes:

cd ../<your-user-name>.github.io
git add .
git commit -m "Update my theme"
git push origin master

The End! Happy Writing With Forestry 🦌

DEV Community: helena ✨