Setting Up Hugo
(Updated: )
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 ¶
- Get Hugo:
port install hugo
- Initialize website:
hugo new site www.vanwerkhoven.org && cd www.vanwerkhoven.org
- Figure out what theme you want (stress!):
git init
git submodule add https://github.com/janraasch/hugo-bearblog.git themes/hugo-bearblog
- Copy contents of
exampleSite
to root - Add new post:
hugo new blog/setting-up-hugo.md
- Publish:
hugo server -D
Tweak theme ¶
Available in my fork
- Add raw html shortcode so I can use html when we really need to
- Ensure images are proportional in responsive mode
- Change font to Helvetica in
themes/hugo-bearblog/layouts/partials/style.html
(Verdana? Really? We’re not Ikea) - Add CSP header because we can
- 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 tostyle.html
Tweak CSS ¶
- Move css from
style.html
tostatic/css/style.css
, import css viathemes/hugo-bearblog/layouts/_default/baseof.html
(this prevents reloading css every page) - Tweak code highlight background (yellow on gray?), use ‘monokailight’ style and ‘monokai’ for dark theme.
- set
noClasses = false
- 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/
- 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
- Load
syntax.min.css
viabaseof.html
- Ensure no
code
orpre
coloring in other css files
- set
- 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 ¶
- Optimize JPG images thread on Stackoverflow.
- 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 alongsidelibjpeg-turbo
. - Use
pngcrush
for PNGs - 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.