Creating a website with Forestry, GitHub, Hugo and Netlify

This article originally appeared on my personal dev blog: Byte High, No Limit.

Back in May 2021 I started a new career as a developer advocate. I first registered my domain back in the 1990s, but it's really just been a placeholder up until now. It's also showing its age. And it doesn't really do for a developer advocate to run their own website on WordPress unless they're hosting it themselves.

During my time as an API writer I built a developer portal using Hugo, and although we ended up self-hosting, I had spoken to both Forestry and Netlify. As a developer, I'm also a long term user of GitHub. So I knew this is the solution I wanted to go with. As a bonus, they all have a free tier for personal websites.

Next, I needed to find a portfolio style Hugo theme that would integrate with all these services. After some searching, I settled on using Kross, a free MIT-licensed theme from Themefisher. It's built on Bootstrap, HTML5 and CSS3.

There are plenty of tutorials on getting going with this kind of setup, so I'll only mention the main gotcha I found. You should click the deploy to Netlify option and then manually configure Forestry.

You'll have the site up and running very quickly, but you'll want to change the placeholder text and images. I found the easiest way to replace the images was directly through the GitHub web interface. When replacing the illustration SVGs, I had to manually edit the files in VS Code to set the correct display size. For the text, save yourself the pain of YAML induced build errors and do it all in Forestry.

The contact form seems to have a dependency on a non-free service, so I've switched it off for now and provided a mailto link instead. There also seems to be a bug in the Portfolio section where, with tags enabled, some content wasn't rendering, so for now I've removed the tags.

I wasn't completely happy with the typography, but originally the entire Kross theme is inherited as a submodule, and I was only overriding the illustrations. That way, if the theme got updated, my site would automatically get updated too. However, there were changes I needed to make and after about a week I replaced the submodule with a local copy of the theme.

With most of the static content now in place, I can concentrate on writing a dev blog. And with Forestry's graphical editor that's going to be super easy, barely an inconvenience.

I had an issue with the SSL/TLS certificate. I resolved it by making andrewowen.net the primary domain and *.andrewowen.net the redirect domain in the Netlify settings.

One tool I find invaluable when working in web applications like Forestry is LanguageTool. It's a multilingual grammar, style and spell checker. The one caveat is that it doesn't seem to check text on Forestry within blockquotes. So if you use it, make sure you do the checking before applying the blockquotes style.

The other thing I learned post-launch is that I should have checked to see how the theme renders all the styles. It was doing some odd things with emphasis and code snippets, so that required some changes to the theme. Fortunately, I only had to edit the style.css file in the theme.

If you're using the Kross theme, I would suggest making the following changes:

ol {
list-style-type: decimal;
margin: 0
}

    ul {
      list-style-type: disc;
      margin: 0
    }

    .content strong {
        font-weight: 700;
        color: #4c4c4c;
        font-size: 15px;
        line-height: 1.8;
        font-family: Roboto, sans
    }

Otherwise, numbers and bullets are missing from lists and the bold (strong) style uses the heading font. I also decided to replace all the fonts with IBM Plex, a free alternative to Helvetica.

I made a change to layouts/index.html to increase the size of the social media icons:

<!-- social icon -->
<ul class="list-unstyled ml-5 mt-3 position-relative zindex-1">
{{ range .Site.Params.social }}
<li style="font-size:32px" class="mb-3"><a class="text-white" href="{{.URL | safeURL }}"><i class="{{.icon}}"></i></a></li>
{{ end }}
</ul>
<!-- /social icon -->

I also removed the email / phone number / address content from the footer. I would expect most people to contact me using one of the social media links on the front page. I've made the icons bigger and added Font Awesome support. Syntax highlighting is supported automatically in Hugo with Chroma, but you have to enable it.

As a follow-up note, at one point I experienced an issue with connecting Forestry to GitHub with the latter complaining about the use of an SHA-1 certificate. I re-added the repo to Forestry and removed the other version, and that seems to have fixed it.

Some other changes I've made since my original post include:

• Updating the blog entries to use syntax highlighting.
• Changing the heading font sizes.
• Removing H3 headings from the blog entires.
• Reducing the top background on the home page.
• Removing the All button from the portfolio (tagging didn't work out of the box).
• Removing the address footer.
• Making some hard-coded paths relative.
• Adding a fav icon.