I’ve used Jekyll in the past, but since change is exciting, here’s a primer to set up your Hugo website, based on their own quickstart. 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

1. Add raw html shortcode so I can use html when we really need to
2. Ensure images are proportional in responsive mode
3. Change font to Helvetica in themes/hugo-bearblog/layouts/partials/style.html (Verdana? Really? We’re not Ikea)
4. Add CSP header because we can
5. Adopt parts of normalize.css: 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 (yellow on gray?), use ‘monokailight’ style 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 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 thread on Stackoverflow.
2. Optionally use mozjpeg: 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 for PNGs
4. Add WebP support with JPG fallback – 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

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.