Getting Back on the Horse - Part 2: Deploying a new Site

meta•website•code

Yeah, so my last post was clearly a bit too optomistic. I've only just now set up this new website using the Hugo static site generator and Academic theme which is pretty nifty. I started doing this back in August, but ran into some snag and haven't returned to it until now.

But I thought I'd briefly go through what I did in order to set this up, mostly as a reference for myself.

Motivation

There are just a few things I really want for my website:

  1. Ability to edit pages and add content using markdown
  2. Good syntax highlighting
  3. Ability to use git for version control

There are a lot of things that sort of work for this. Jekyll seems to be the most common, and I've tried it before, but it seemed a bit too sparse. And I didn't love the way it looked, or the structure of the folder structure to make it work. Then I tried Grav and one of its git-enabled themes, but it seemed too complicated for my needs.

My main website is currently through Squarespace, and it looks pretty, but I can't easily manage posts in text files with version control. In principle, I could write posts in markdown and upload those files, but that's clunky, and anyway and it's syntax highlighting isn't quite up to snuff (or wasn't last I checked).

So, enter Hugo.

Set-up

Honestly, this is dead simple. I followed the Getting Started page in the Hugo docs, and the same for the Academic theme. Only a couple of modifications:

First, when installing the theme, I used a git submodule rather than just straight cloning. In other words, after installing hugo with homebrew:

$ mkdir hugo-nequalsme
$ cd hugo-nequalsme
$ git init
Initialized empty Git repository in /Users/kev/computation/websites/hugo-nequalsme/.git/
$ git submodule add https://github.com/gcushen/hugo-academic.git themes/academic
Cloning into '/Users/kev/computation/websites/hugo-nequalsme/themes/academic'...
remote: Counting objects: 2334, done.
remote: Compressing objects: 100% (57/57), done.
remote: Total 2334 (delta 28), reused 34 (delta 11), pack-reused 2263
Receiving objects: 100% (2334/2334), 3.43 MiB | 3.48 MiB/s, done.
Resolving deltas: 100% (1340/1340), done.
$ cp -a themes/academic/exampleSite/* .

Dealing with submodules is a bit tricky, but for the most part I won't be needing to actively worry about it.

Then I created a new repo on github, added all of the demo content, and pushed it.

$ git remote add origin git@github.com:kescobo/nequals.me.git
$ git push -u origin master

Customizing

Again, I basically just followed the theme docs to modify my config.toml and all of the content pages. I had some posts left over from previous static site attempts and moved them over to the content/post/ folder.

This is mostly straightforward, and I tried to do atomized commits to the repo so it should be clear from the history. Part of the customization was commenting out or disabling all of the stuff I don't want for now. Happily - the content is still there if I ever want it later.

Deploying

Unfortunately, I can't go through this in detail, because I got a big chunk of it set up a while ago. The good news is, the folks at Reclaim Hosting are awesome. I've filed a bunch of help tickets when I was trying to get Grav working, and they were prompt and super helpful.

So the background here is that I already have a domain registered through hover, and I've got them pointing at my hosting at Reclaim. Honestly, this part gave me some trouble when I initially did it, because I had tweaked all kinds of stuff before, but if you're starting from scratch the docs are pretty good.

What I did today was to effectively clear out the public_html/ folder on the server that had all of the crap from the previous Grav blog, and then I just needed to build my Hugo site locally and transfer it up to the server. Building the site is easy - you just:

$ hugo
Started building sites ...

Built site for language en:
0 draft content
0 future content
0 expired content
26 regular pages created
29 other pages created
0 non-page files copied
20 paginator pages created
18 tags created
0 categories created
1 publication_types created
total in 64 ms

This generates the entire html structure in a new folder public/. To transfer it, I'm using rsync.

$ rsync -avzP --delete public/ <username>@nequals.me:/home/<username>/public_html/

The flags for rsync are:

  • -a: archive mode (does a bunch of worthwhile stuff see here)
  • -v: verbose
  • -z: compresses stuff before transferring and decompresses on the other side (reduces bandwidth needed)
  • -P: shows progress meters for large files
  • --delete: removes stuff that's not in the source directory anymore

That last piece is useful if you're playing around with the folder structure, because files that aren't modified remain there, so you might end up with a lot of crap floating around your webpage otherwise.

I also set up an alias in my .bashrc file to make this easier:

alias hugopush="rm -rf public/; hugo; rsync -avzP --delete public/ <username>@nequals.me:/home/<username>/public_html/"

And that's it! At some point I'll want to look into how I can do webhooks or something so that I can just push to github and have the site building happen right on the server, but as it stands, this is pretty seemless. I write the markdown file, commit changes, and run hugopush and I'm done!