Tim's blah blah blah

Setting Up Hugo

(Updated: )

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.


Initial setup

  1. Get Hugo:
port install hugo
  1. Initialize website:
hugo new site www.vanwerkhoven.org && cd www.vanwerkhoven.org
  1. Figure out what theme you want (stress!):
git init
git submodule add https://github.com/janraasch/hugo-bearblog.git themes/hugo-bearblog
  1. Copy contents of exampleSite to root
  2. Add new post:
hugo new blog/setting-up-hugo.md
  1. 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

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}"

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


  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">}}


/* Figure placement CSS - based on http://www.ebadf.net/2016/10/19/centering-images-in-hugo/ */
  display: block;
  margin: 0.7rem auto;
  margin: 0.7rem;
  margin: 0.7rem;
  max-width: 100%
  max-width: 50%
  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>

#Markdown #Server