Using SASS with Hugo

3 minutes read

Built-in SASS support

You need to have the Hugo extended version for SASS/SCSS processing.

It is only the extended version of Hugo that comes with in-built Sass support, starting from version 0.43.

Sass provides many benefits that simplify working with CSS styles. For example, it enables the use of variables for CSS values.

file_type_scss2 Main.scss 
$font: Helvetica, sans-serif;
$primary-color: #333;
body {
  font: 100% $font;
  color: $primary-color;
}

This is especially useful for experimenting with your web design, since you can quickly change the appearance of any element. Further, partial SAAS files allow you to better organize your CSS. The file names of such files begin with an underscore. These are then imported and combined into a single .scss file.

Configuring a SASS pipeline

In order to setup a SASS pipeline with Hugo, you need to

  1. put your scss file in the assets directory
  2. load the file as a resource and use the Hugo pipes to compile it to CSS
  3. use the compiled CSS as an external or internal CSS.

The compilation happens automatically when you run the build command hugo or hugo server.

Adding external style sheet

Now you can include the following under <head>.

{{ $main_options := (dict "targetPath" "css/site.css" "outputStyle" "compressed") }}
{{ $main_template := resources.Get "sass/main.scss" }}
{{ $main_style := $main_template | resources.ExecuteAsTemplate "main_parsed.scss" . | toCSS $main_options | resources.Minify }}

<link rel="stylesheet" href="{{ $main_style.RelPermalink }}">

There are two files involved in the above code. The sass/main.scss file is the one where you call all the the scss partials. resources.Get which can be used to “get a resource” that can be further processed. The SCSS processor is a Resource transformation step and it can be chained with the many others in a pipeline. New Resource transformation funcs:

  • resources.ToCSS: Compile SCSS or SASS into CSS.
  • resources.PostCSS: Process your CSS with PostCSS. Config file support (project or theme or passed as an option).
  • resources.Minify: Currently supports minification of css, js, json, html, svg, xml.
  • resources.Fingerprint: Creates a fingerprinted version of the given Resource with Subresource Integrity
  • resources.Concat: Concatenates a list of Resource objects.
  • resources.ExecuteAsTemplate: Parses and executes the given Resource and data context (e.g. .Site) as a Go template.

To use it though, all we need to do is apply resources.Fingerprint on our resource. Once done, Hugo will add a new property, .Data.Integrity to the resource object. Because we already .Fingerprinted our script above, we can just drop this: What happens here is that Hugo will first fetch a resource file from the assets directory. That file is “piped” to the ToCSS processor which uses the file and a map of options to generate the CSS file. Here I’m passing the outputStyle: compressed which minifies the CSS to save some bandwidth.

Further reading