Moving to GitHub Pages, Pt.2

Further on Hosting Stuff with GitHub Pages

Let’s repeat my ToDo list of the last blog post here and see where we are:

• create blog locally
• add content
• setup github pages
• add github action to auto deploy
• update DNS zone
• enable comments
• enable share links
• add meaningful content

Not too bad? But how did we arrive here?

Hosting under custom domain

In theory that’s quite easy. Once you have GitHub Pages set up your page will already be available as username.github.io. Nothing wrong with that, but I wanted it to act as my main homepage at the same time. This means convincing GitHub to recognize and accept requests for this host (andreaseisele.com) and to provide the content in the appropriate repo.

Two things need to be in place for this to work. A static file called  CNAME must be created in the git repository. This file needs to hold the custom domain (think www.example.com). There is a settings UI on GitHub itself to create this but in my case I had to let Hugo supply the file in the deployment. Therefore it needs to be created in the static folder.

Next is updating the DNS Zone of the domain in question. This of course varies depending on the DNS Provider but what needs to be done is this:

• have the so called apex / root domain (example.com) point to GitHub’s IP addresses
• add a CNAME record for the www subdomain (www.example.com) pointing to username.github.io

There is a wonderful answer on  Stackoverflow going into all the necessary details and background info.

Your zone should look something like this in the end:

Enabling HTTPS

It turns out this step is easy. If everything is set up correctly, especially the DNS stuff, all one needs to do is to enable a setting in the repository config. Notice how it picked up the custom domain setting right out of the static CNAME file.

This in turn will use Let’s Encrypt behind the covers to generate a new certificate for the custom domain. There is even a progress bar on this page initially for one to check the certificate status.

I went through some hiccups to get this to work for my site because of a combination of DNS TTL / cache inconveniences and me missconfiguring my initial CNAME record.

Enabling Comments

Luckily the theme I’m using has support for various comment engines. Initially I’d decided to not enable comments at all because I didn’t want to store user input on my side and / or propagate it to third parties. So services like Disqus or Commento are out of the picture.

Still while browsing the configuration options available I came upon something interesting named Utterances. It works as a combination of something called a GitHub App, a bot service and some JavaScript to be used on the target page. The actual comments are stored as GitHub Issues with a custom tag on a GitHub repository one has to provide.

I’ve enabled utterances in my global site configuration like this:

[params.page.comment]
    enable = true

        [params.page.comment.utterances]
            enable = true
            repo = "aeisele/andreaseisele.com-comments"
            issueTerm = "pathname"
            label = "blog-comment"
            lightTheme = "github-light"
            darkTheme = "github-dark"

If everything works according to plan you should be able to see a comments form right under this post. 🤞

The problem is this will apply to all content. I’m really not keen on comments on my legal disclaimer pages, so one needs to disable the global config again on static pages via the frontmatter like this:

comment:
    enable: false
    utterances:
        enable: false

Enabling (Social) Sharing

Again in my first post I said I don’t really understand the necessity of social share buttons. Then again I figured it doesn’t hurt to provide it nevertheless. This was really easy to do via configuration:

[params.page.share]
    enable = true
    Twitter = true
    LinkedIn = true
    HackerNews = true
    Reddit = true
    Xing = true

Technically this theme supports a lot more sharing options but I limited it to sites I use myself. You will not find a Facebook button on my blog. 😎