The extended version of Hugo includes LibSass to transpile Sass to CSS.
From the LibSass home page:
LibSass is now deprecated—new projects should use Dart Sass instead.
Including the Dart Sass transpiler, in the same way we include the LibSass transpiler, may be possible in the future, but you do not have to wait.
Installation
Local development
When you install the Dart Sass transpiler somewhere in your PATH, Hugo will find it. You can install a prebuilt binary, or use a package manager.
| Package manager | OS | Site | Installation |
|---|---|---|---|
| Chocolatey | Windows | chocolatey.org | choco install dart-sass-embedded |
| Scoop | Windows | scoop.sh | scoop install dart-sass-embedded |
| Snap | Linux | snapcraft.io | sudo snap install dart-sass-embedded |
| Homebrew | macOS, Linux | brew.sh | brew install sass/sass/dart-sass-embedded |
The Hugo Snap package includes the Dart Sass transpiler. You do not need to install the transpiler.
CI/CD deployment
For CI/CD deployment (e.g., GitHub Pages, Netlify, etc.) you must edit the workflow to install the Dart Sass transpiler before Hugo builds the site[1]. Some providers allow you to use one of the package managers above, or you can download and extract the prebuilt binary.
GitHub Pages
To install the Dart Sass transpiler for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:
- name: Install Dart Sass Embedded
run: sudo snap install dart-sass-embedded
If you are using GitHub Pages for the first time with your repository, GitHub provides a starter workflow for Hugo that includes the Dart Sass transpiler. This is the simplest way to get started.
Netlify
To install the Dart Sass transpiler for your builds on Netlify, the netlify.toml file should look something like this:
[build]
publish = "public"
command = """\
npm install sass-embedded-linux-x64@${DART_SASS_VERSION} && \
mkdir -p /opt/build/repo/node_modules/.bin && \
cp -r /opt/build/repo/node_modules/sass-embedded-linux-x64/dart-sass-embedded/* /opt/build/repo/node_modules/.bin/ && \
dart-sass-embedded --version && \
hugo --gc --minify \
"""
[build.environment]
HUGO_VERSION = "0.108.0"
DART_SASS_VERSION = "1.58.3"
TZ = "America/Los_Angeles"
You can also use the Homebrew package manager to install the Dart Sass transpiler, but the installation is slow (90 seconds). The npm method described above takes 5 seconds, and Netlify caches the executable for future builds.
Verification
With Hugo v0.108.0 and later, run hugo env to verify that the Dart Sass transpiler is available to Hugo.
Usage
To use the Dart Sass transpiler while building your site, specify the transpiler in the options passed to resources.ToCSS. For example:
{{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }}
{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
Testing
Add this to your Sass file:
@use "sass:math";
body {
font-size: math.div(144px, 2);
}
It will fail with LibSass. With Dart Sass your font size will be 72px.
Miscellaneous
If you compile Hugo locally, and run mage test -v, the test will fail if you are using the Snap package. This is probably due to the Snap package’s strict confinement.
-
You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set
useResourceCacheWhentoneverin your site configuration, and (c) you add and commit your resources directory to your repository. ↩︎