css.Sass

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

enableSourceMap

(bool) Whether to generate a source map. Default is false.

includePaths

(slice) A slice of paths, relative to the project root, that the transpiler will use when resolving @use and @import statements.

outputStyle

(string) The output style of the resulting CSS. With LibSass, one of nested (default), expanded, compact, or compressed. With Dart Sass, either expanded (default) or compressed.

precision

(int) The precision of floating point math. Applicable to LibSass. Default is 8.

silenceDeprecations

New in v0.139.0

(slice) A slice of deprecation IDs to silence. IDs are enclosed in brackets within Dart Sass warning messages (e.g., import in WARN Dart Sass: DEPRECATED [import]). Applicable to Dart Sass. Default is false.

silenceDependencyDeprecations

New in v0.146.0

(bool) Whether to silence deprecation warnings from dependencies, where a dependency is considered any file transitively imported through a load path. This does not apply to @warn or @debug rules.Default is false.

sourceMapIncludeSources

(bool) Whether to embed sources in the generated source map. Applicable to Dart Sass. Default is false.

targetPath

(string) The publish path for the transformed resource, relative to thepublishDir. If unset, the target path defaults to the asset’s original path with a .css extension.

transpiler

(string) The transpiler to use, either libsass or dartsass. Hugo’s extended and extended/deploy editions include the LibSass transpiler. To use the Dart Sass transpiler, see the installation instructions. Default is libsass.

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;

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"
    "vars" site.Params.styles
    "includePaths" (slice "node_modules/bootstrap/scss")
  }}
  {{ 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 }}

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¹ 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.

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². 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

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.144.2
  DART_SASS_VERSION: 1.85.0
  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.144.2"
DART_SASS_VERSION = "1.85.0"
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 \
  """