css.Sass

Transpiles Sass to CSS.

{{ with resources.Get "sass/main.scss" }}
  {{ $opts := dict
    "enableSourceMap" (not hugo.IsProduction)
    "outputStyle" (cond hugo.IsProduction "compressed" "expanded")
    "targetPath" "css/main.css"
    "transpiler" "libsass"
  }}
  {{ with . | toCSS $opts }}
    {{ if hugo.IsProduction }}
      {{ with . | fingerprint }}
        <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
      {{ end }}
    {{ else }}
      <link rel="stylesheet" href="{{ .RelPermalink }}">
    {{ end }}
  {{ end }}
{{ end }}

Transpile Sass to CSS using the LibSass transpiler included in Hugo’s extended and extended/deploy editions, or install Dart Sass to use the latest features of the Sass language.

Sass has two forms of syntax: [SCSS] and [indented]. Hugo supports both.

Options #

transpiler: (string) The transpiler to use, either libsass (default) or dartsass. Hugo’s extended and extended/deploy editions include the LibSass transpiler. To use the Dart Sass transpiler, see the installation instructions below.
targetPath: (string) If not set, the transformed resource’s target path will be the original path of the asset file with its extension replaced by .css.
vars: (map) A map of key-value pairs that will be available in the hugo:vars namespace. Useful for initializing Sass variables from Hugo templates.

// LibSass
@import "hugo:vars";

// Dart Sass
@use "hugo:vars" as v;

outputStyle: (string) Output styles available to LibSass include nested (default), expanded, compact, and compressed. Output styles available to Dart Sass include expanded (default) and compressed.
precision: (int) Precision of floating point math. Not applicable to Dart Sass.
enableSourceMap: (bool) If true, generates a source map.
sourceMapIncludeSources: (bool) If true, embeds sources in the generated source map. Not applicable to LibSass.
includePaths: (slice) A slice of paths, relative to the project root, that the transpiler will use when resolving @use and @import statements.

{{ $opts := dict
  "transpiler" "dartsass"
  "targetPath" "css/style.css"
  "vars" site.Params.styles
  "enableSourceMap" (not hugo.IsProduction)
  "includePaths" (slice "node_modules/bootstrap/scss")
}}
{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
  <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}

silenceDeprecations: (slice) A slice of deprecation IDs to silence. The deprecation IDs are printed to in the warning message, e.g “import” in WARN Dart Sass: DEPRECATED [import] .... This is for Dart Sass only.

Dart Sass #

Hugo’s extended and extended/deploy editions include [LibSass] to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass].

Use the latest features of the Sass language by installing Dart Sass in your development and production environments.

Installation overview #

Dart Sass is compatible with Hugo v0.114.0 and later.

If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass.

If you install Hugo as a [Snap package] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass.

Installing in a development environment #

When you install Dart Sass somewhere in your PATH, Hugo will find it.

OS	Package manager	Site	Installation
Linux	Homebrew	[brew.sh]	`brew install sass/sass/sass`
Linux	Snap	[snapcraft.io]	`sudo snap install dart-sass`
macOS	Homebrew	[brew.sh]	`brew install sass/sass/sass`
Windows	Chocolatey	[chocolatey.org]	`choco install sass`
Windows	Scoop	[scoop.sh]	`scoop install sass`

You may also install [prebuilt binaries] for Linux, macOS, and Windows.

Run hugo env to list the active transpilers.

Installing in a production environment #

For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.

GitHub Pages #

To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:

- name: Install Dart Sass
  run: sudo snap install dart-sass

If you are using GitHub Pages for the first time with your repository, GitHub provides a [starter workflow] for Hugo that includes Dart Sass. This is the simplest way to get started.

GitLab Pages #

To install Dart Sass for your builds on GitLab Pages, the .gitlab-ci.yml file should look something like this:

variables:
  HUGO_VERSION: 0.141.0
  DART_SASS_VERSION: 1.83.4
  GIT_DEPTH: 0
  GIT_STRATEGY: clone
  GIT_SUBMODULE_STRATEGY: recursive
  TZ: America/Los_Angeles
image:
  name: golang:1.20-buster
pages:
  script:
    # Install Dart Sass
    - curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
    - tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
    - cp -r dart-sass/* /usr/local/bin
    - rm -rf dart-sass*
    # Install Hugo
    - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    - apt install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    # Build
    - hugo --gc --minify
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Netlify #

To install Dart Sass for your builds on Netlify, the netlify.toml file should look something like this:

[build.environment]
HUGO_VERSION = "0.141.0"
DART_SASS_VERSION = "1.83.4"
NODE_VERSION = "22"
TZ = "America/Los_Angeles"

[build]
publish = "public"
command = """\
  curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
  tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
  rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
  export PATH=/opt/build/repo/dart-sass:$PATH && \
  hugo --gc --minify \
  """

Example #

To transpile with Dart Sass, set transpiler to dartsass in the options map passed to css.Sass. For example:

{{ with resources.Get "sass/main.scss" }}
  {{ $opts := dict
    "enableSourceMap" (not hugo.IsProduction)
    "outputStyle" (cond hugo.IsProduction "compressed" "expanded")
    "targetPath" "css/main.css"
    "transpiler" "dartsass"
  }}
  {{ with . | toCSS $opts }}
    {{ if hugo.IsProduction }}
      {{ with . | fingerprint }}
        <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
      {{ end }}
    {{ else }}
      <link rel="stylesheet" href="{{ .RelPermalink }}">
    {{ end }}
  {{ end }}
{{ end }}

Miscellaneous #

If you build Hugo from source and run mage test -v, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package’s strict confinement model.