Notes on Site Build and Deploy

Hugo, Gitlab, and Netlify, etc.

7 minute read

So I thought that as I created a Hugo based site, I’d keep running notes of what issues I encountered and what I did about them. That way later on I could refer back to know what the hell I was thinking when x came up.

Then I charged forward, did most of the research on tablet, and just otherwise completely ignored my plan.

So instead, here’s my recollection of a few things that I do sort of recall…

Notes

site relative vs. relative root URLs

One of the biggest issues I ran across were some theme files had URL references in them to project files, like css or js, etc., that were given as root relative urls, eg. ref="/css/somestyle.css" Similar issues occured when themes would create their own url to a post, category, etc. Fixes generally involved using the hugo RelURL function.

baseURL

In my hugo site directory, I had intended to keep the baseURL as “/” as many themes and articles I’d read suggested. Hugo server itself ignores the setting by default when running locally, but since I wasn’t sure where (all) I’d be deploying to anyway, it seemed to me like keeping everything relative was a good thing. Unfortunately, I found that I needed to set the baseURL more fully for a couple reasons.

In the case of netlify and gitlab/github user sites, it almost worked to use /, but due to the way the internal template for integrating disqus provides the url (using the .Permalink variable), if baseURL is relative, then so will be the url provided to disqus, which keeps it from embedding properly.

In the case of gitlab and github project sites, the site URL becomes something like http://name.gitlab.io/project/ so having the baseURL as / led to bad links. Obvious now, but I for some reason just thought everything would magically work with / getting interpreted as project root and the site somehow knowing to prepend the directory part of the initial url. Stopping to think about it though - don’t see how it could. I suppose this partly goes back to root relative urls getting peppered through things vs. more disciplined usage of relative urls.

Regardless, the easy fix in both deploy situations was to use the hugo command line base url arg, like so: -baseURL=https://myorg.gitlab.io/projectname/, in my CI build instructions. That was stuck in .gitlab-ci.yml in my case for gitlab.

and -baseURL=https://rob.loc.net/ for netlify.

I am still not sure I should be putting the http(s): part in the url, but I saw no examples with anything that was just like //rob.loci.net/. It seems to work as far as basic site gen with hugo is concerned, but disqus still won’t load with it not having the http: or https: at the start.

I thought I ran into an issue with not having a trailing slash on baseURL, at least in the config.toml, though it seemed to work fine using --baseURL=mymachinename.local with hugo server on the command line, so not sure if it always in all cases adds a / if one isn’t already on the baseURL, or not.

Other Gitlab CI and Netlify deploy notes:

The most popular Hugo Docker image publysher/hugo was recently updated to latest hugo and includes git, but examples exist to use a small base image then manually add hugo should the need arise.

Git submodules

I have a git submodule in my project. It contains the theme, which I host separately on github as a fork from the original dev. I found that while netlify automatically pulled the submodule contents during it’s build step (kudos to netlify on that 👍), gitlab does not. However, since current versions of the docker image contain git, I was able to just do this in my .gitlab-ci.yml script:

image: publysher/hugo

pages:
    script:
    - git submodule update --init --recursive
    - hugo --baseURL="https://intelligence.gitlab.io/musings/"
    artifacts:
      paths:
      - public
    only:
    - master

There are alternate approaches to do it in a before-script section. Since there’s just one job, I didn’t see any difference.

Checking progress was easy on both platforms.

Just go to the pipeline view in gitlab, click on the build status button, and you can see it running live. Cool.

On Netlify, same sort of thing, but is even simpler. It’s a nice interface.

Netlify setup

In general, I’m really impressed with netlify. They have a pretty polished setup. I still have to go through the hooks and triggers stuff to try out the deploy preview stuff with slack, etc. integration. And I’d like to try out the Pro tier’s git branch support. It’d be nice if there were ez-button type help with some of those integrations similar to what they have with the rest of site setup, but not sure how possible that’d be. update: I set up notifications, etc. and it was pretty straightforward.

I am trying out their pro plan using the new (awesome) free for non-commercial / open source feature. I note that they don’t have password support show up on their dashboard like they are supposed to - I haven’t contacted them about it. I am guessing they took that out of the pro tier if you are using it for free. Too bad, because I can definitely see it being useful for branch-deploys in particular as well as internal portions of a site.

Other notes

Hugo on Sierra

Turns out the 4th beta of Sierra broke go for a while, which in turn breaks Hugo.

I started having lots of issues with livereloading and hugo crashing during site (re)gen, to the point where I’d have to rerun the hugo server command after most changes, and run it more than once often, till it got through without crashing.

I had installed using brew, but I couldn’t really (easily) use it to update to a patched version of go because it had to be applied manually. I ended up installing a binary build from the Go site, which worked fine, but then wouldn’t work with brew to allow me to recompile Hugo. I’m sure I could have figured that out if I had more brew packaging and use experience, but since I used brew to make it easier, I didn’t want to take the time to do that vs. just get back to work. So I used go’s package facility to grab, build, and install hugo and it was pretty painless.

Hugo config.toml differences

When trying out different themes, one annoying thing I discovered were different themes using varying ways of specifying commonly used options in the config.toml. For example, author info, copyright info, site description/about type stuff, social integration

Different themes obviously are going to have different configuration needs, but it’d be nice to see more common, best practice, type suggestions in the Hugo docs and to have theme authors pay more attention to them.

Hugo shortcodes

Odd thing I came across. I started using a blockquote shortcode and noticed if I didn’t have the named params (or at least the link param) followed by an = with no space between them, it would throw an error and not render the rest of the page. The error was (for example):

ERROR: 2016/08/13 11:14:52 shortcode.go:287: AI-Q&A-Yann-LeCun:19: got positional parameter 'link'. Cannot mix named and positional parameters.

I didn’t think whitespace should matter like that, but haven’t tracked down if it’s my misunderstanding, or something odd about that shortcode in particular.

So many that I used before starting to take notes… Maybe I’ll get them in here eventually.

The Hugo docs site and discussion forums were great. So were the github Hugo issues page.

http://viewfinderdesign.co.uk/archive/674/tips-for-building-a-site-with-hugo/

http://atchai.com/blog/the-cms-is-dead-long-live-hugo-wercker-proseio-and-cloudfront/

http://zackofalltrades.com/notes/2014/05/hugo-from-scratch/

There were many others, including many that were extremely helpful. As I revisit them, I’ll try to remember to add them to the post.

comments powered by Disqus