I’ve used Jekyll (jekyllrb.com) in the past, but since change is exciting, here’s a primer to set up your Hugo (gohugo.io) website, based on their own quickstart (gohugo.io). After initial setup and installation of the bear theme, I provide some theme tweaks to enrich and speed up the page, especially on responsive images, giving a higher speedranking score while at it.

Contents

Initial setup ¶

1. Get Hugo:

port install hugo

2. Initialize website:

hugo new site www.vanwerkhoven.org && cd www.vanwerkhoven.org

3. Figure out what theme you want (stress!):

git init
git submodule add https://github.com/janraasch/hugo-bearblog.git themes/hugo-bearblog

4. Copy contents of exampleSite to root
5. Add new post:

hugo new blog/setting-up-hugo.md

6. Publish:

hugo server -D

Tweak theme ¶

Available in my fork (github.com)

1. Add raw html shortcode (anaulin.org) so I can use html when we really need to
2. Ensure images are proportional (stackoverflow.com) in responsive mode
3. Change font to Helvetica in themes/hugo-bearblog/layouts/partials/style.html (Verdana? Really? We’re (idsgn.org) not (nationalpost.com) Ikea (theguardian.com))
4. Add CSP header (mozilla.org) because we can
5. Adopt parts of normalize.css (github.io): mkdir -p static/css && wget https://necolas.github.io/normalize.css/latest/normalize.css -P static/css/, add minified code to style.html

Tweak CSS ¶

1. Move css from style.html to static/css/style.css, import css via themes/hugo-bearblog/layouts/_default/baseof.html (this prevents reloading css every page)
2. Tweak code highlight background (gohugo.io) (yellow on gray?), use ‘monokailight’ style (github.io) and ‘monokai’ for dark theme.
   1. set noClasses = false
   2. Generate css for light and dark

   hugo gen chromastyles --style=monokai > syntax.dark.css
   hugo gen chromastyles --style=monokailight > syntax.light.css
   mv syntax.*.css static/css/
   

   1. Splice together depending on requested color scheme.

   echo "@media (prefers-color-scheme: light) {" > syntax.css
   cat syntax.light.css >> syntax.css
   echo "} @media (prefers-color-scheme: dark) {" >> syntax.css
   cat syntax.dark.css >> syntax.css
   echo "}" >> syntax.css
   minify syntax.css > syntax.min.css
   

   1. Load syntax.min.css via baseof.html
   2. Ensure no code or pre coloring in other css files
3. Minify CSS (github.com) for speed (save 0.8 kiB!!11)

Tweak images ¶

You can (should) optimize your images for web use, to a) reduce size and b) anonymize/prevent information leak you might not want. I use Imagemagick’s convert utility for this as follows: convert -strip -interlace Plane -gaussian-blur 0.05 -quality 50% -resize 1440 source result

• -strip strip exif/profiles/comments
• -interlace Plane something something from stackoverflow
• -gaussian-blur 0.05 slight blurring to compress easier
• -quality 50% lowest quality I find tolerable for web (remember: people will look at your pictures for only 1.2 seconds, not crop to 100% to inspect JPEG artifacts ;))
• -resize 1440 resize to width of 1440 pixels (see ‘Serve responsive images’ why)

To run on all files:

find . -type f -not -iname "*web*" -iname "IMG_*" | while read file; do                               
    outfile="${file%.*}-web.jpg"; test -f "${outfile}" || convert -strip -interlace Plane -gaussian-blur 0.05 -quality 50% -resize 1440 "${file}" "${outfile}"
done

For PNG, reducing the palette does wonders: convert input.png -colors 255 -type palette -geometry 1440 output.png or sometimes this helps convert input.png -colors 255 -type palette -geometry 1440 PNG8:output.png Alternatively/additionally, one can use pngcrush pngcrush -reduce -brute input.png output.png

Sources ¶

1. Optimize JPG images (stackoverflow.com) thread on Stackoverflow.
2. Optionally use mozjpeg (mozilla.org): e.g. cjpeg -quality 65 foo.bmp > bar.jpg. I couldn’t get this to work because macports doesn’t support this alongside libjpeg-turbo.
3. Use pngcrush (wikipedia.org) for PNGs
4. Add WebP support with JPG fallback (stackoverflow.com) – not yet because Hugo doesn’t support this yet / too experimental / too little benefit

Enable floating images ¶

Sometimes I want an image of smaller width floating with text. I adopted a solution that ebadf.net already found out (ebadf.net)

Example use ¶

For an image floating right at half width of the column, use this code (read below on what sizes is doing):

{{< fig src="images/tim1837.jpg" link="images/tim1837.jpg" alt="Tim van Werkhoven by Cima" class="floatright half-width" sizes="(min-width: 720px) 360px, 50vw">}}

Source ¶

/* Figure placement CSS - based on http://www.ebadf.net/2016/10/19/centering-images-in-hugo/ */
.center{
  display: block;
  margin: 0.7rem auto;
}
.floatleft{
  float:left;
  margin: 0.7rem;
}
.floatright{
  float:right;
  margin: 0.7rem;
}
.full-width{
  max-width: 100%
}
.half-width{
  max-width: 50%
}
.third-width{
  max-width: 30%
}

Serve responsive images & image grids ¶

For even more tweaking on responsive design and images, read Responsive images & image grids for Hugo (vanwerkhoven.org).

Show domain in links ¶

I want my links to show as [link text](domain.com/page) as “link text (domain.com)”. This could be possible using custom shortcodes (gohugo.io) attached to Hugo render hooks (gohugo.io) like this one (stenbrinke.nl). These snippets are written in Go Template language (gomplate.ca), or ‘gomplate’.

To achieve this, I created the following shortcode for render-link.html:

{{- $u := urls.Parse (absURL .Destination) -}}
{{- $splitHostname := split $u.Hostname "." -}}
{{- $domain := delimit (last 2 $splitHostname) "." -}}
<a href="{{ .Destination | safeURL }}"{{- with .Title}} title="{{ . }}"{{ end -}}>{{ .PlainText | safeHTML }} ({{ $domain }})</a>