How this site is built

2021-04-24

I currently use Hugo to generate the site content from markdown. The content is hosted by Netlify. The source for this site is on GitHub.

Generating site content

I want a simple tool that allows full control over the content I publish, and isn’t too difficult to maintain. Below are some more specifics, and how Hugo provides.

Must have

Nice to have

Some more details

Syntax highlighting

Syntax highlighting works out of the box with Hugo, and is done at build time, resulting in smaller page sizes than bundling a JavaScript syntax highlighter like highlight.js. For example, writing the following markdown results in the syntax snippet below:

```js
const main = () => { console.log("Hello world!"); }
```

const main = () => { console.log("Hello world!"); }

RSS

This took more effort than I expected. By default, Hugo generates an RSS feed for your home page, and each ‘section’ of your site, such as ~/blog, ~/about. I couldn’t figure out how to disable this, so I ended up deleting these files after generation in my ‘publish’ script. See this site’s source for more information.

Also, Hugo’s default RSS template only shows a summary of each article in the feed, which I find annoying when reading articles via my RSS aggregator. See RSS: Summary or full text? for more information about choosing between a summary or full text in your RSS feed.

Would it be easier to just write the HTML & CSS myself?

Probably not. Markdown is easier to read & edit, and Hugo generates HTML that I don’t need to tweak afterwards.

Other static site generators considered

Both of these are based on React, which put me off for a simple blog that could be hand-written in HTML. I also assumed Hugo would be faster, being written in go.

I’ve also briefly used Jekyll with GitHub Pages. It was a bit slow, and getting it working on GitHub took more effort than I had patience for. Also being a Windows user, the Ruby usage put me off.

Hosting

I chose Netlify due to its easy management of everything I could think of, and more. I could learn a lot by building my own infrastructure on AWS or another cloud provider, but that’s not the intention of this site.

Here’s what I want from hosting, and how Netlify provides.

Must have

Nice to have

Some extra things that Netlify provides, that I hadn’t thought about:

Pushing updates to this site is as simple as pushing to my GitHub repo. Netlify watches my repo for updates and deploys them.

I configured my Netlify site to not do any build step. I simply build my site content locally with Hugo, include the published content in my git repo, and push to GitHub to publish new content. This removes complication from the publishing process. One complication I ran into was git submodules, which Hugo uses for themes. Netlify couldn’t clone my theme submodule. Instead of trying to figure that out, I just included my theme as regular files in my repo.

Other hosting options considered

Hugo-aware

All of these have HTTPS, deploy on push, and custom domain options. The drawback is that you rely on their support of Hugo. For a simple blog, pushing the rendered HTML + CSS from my dev machine seems good enough.

Others

References and further reading