Hello, World

Hello, world. Hopefully, this blog will motivate me to ask more interesting questions and to find and share satisfying answers. I also find that writing forces me to clarify my thinking and move ideas from volatile to persistent storage.

I think documenting how the site is built is a good place to start. I aim to keep the stack as simple as possible, while reserving the freedom to swap out components with minimal hassle.

The set-up was fairly straightforward.

  1. Create a joshklop.github.io repository.

  2. Register the domain name with Cloudflare (unnecessary if one is willing to have a username.github.io domain).

    I have what the Cloudflare documentation calls a “full setup”, using Cloudflare for domain registration and authoritative DNS servers.

  3. Add two CNAME records mapping joshklop.com and www.joshklop.com to joshklop.github.io. I set both to proxy through Cloudflare.

    Interestingly, the DNS RFC does not technically allow the “apex domain” joshklop.com to be used as the alias in a CNAME record. Cloudflare does some additional internal resolution (CNAME flattening) to allow it while still semantically matching the spec. GitHub Pages would otherwise require us to follow the DNS spec by creating an A record mapping to a GitHub IP address, which could change. See this detailed post for the request-response flow with one A and one CNAME record.

  4. Add a CNAME file to GitHub with the www.joshklop.com subdomain.

    GitHub will create a CNAME record mapping joshklop.github.io to www.joshklop.com. The post linked above shows the impact on requests and responses. Now, we should be able to access our site using joshklop.com, www.joshklop.com, or joshklop.github.io.

  5. Configure security-related settings. Under the “SSL/TLS” tab in “Edge Certificates”, enable “Always Use HTTPS”, “Opportunistic Encryption”, “TLS 1.3”, and “Automatic HTTPS Rewrites”.

  6. Hugo and theming. To install Hugo, I used:

    go install -tags extended github.com/gohugoio/hugo@latest
    

    The excellent Hugo documentation contains concise tutorials for different users’ needs that aren’t worth summarizing here.

  7. Add a workflow to the repository to automatically build and deploy the site. I based mine on the sample from the Hugo documentation.

All done!