HUGO
Menu
GitHub 90480 stars Mastodon

css.Sass

Returns a resource created by transpiling the given Sass resource to CSS.
Syntax
css.Sass [OPTIONS] RESOURCE
Returns
resource.Resource
Alias
toCSS

Transpile Sass to CSS using the Dart Sass transpiler. To use this function, you must first install Dart Sass.

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

Options

The css.Sass function accepts an options map.

enableSourceMap
(bool) Whether to generate a source map. Default is false.
{{ $opts := dict "enableSourceMap" true }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}
importContext
New in v0.165.0
(resource.ResourceGetter) A resource getter to use when resolving @use and @import statements. Hugo searches this context first, matching by the path as written in the statement, before falling back to the file system.
includePaths
(slice) A slice of paths, relative to the project root, that the transpiler will use when resolving @use and @import statements.
{{ $opts := dict "includePaths" (slice "node_modules/bootstrap/scss") }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}
outputStyle
(string) The output style of the resulting CSS, either expanded or compressed. Default is expanded.
{{ $opts := dict "outputStyle" "compressed" }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}
silenceDeprecations
(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]).
{{ $opts := dict "silenceDeprecations" (slice "import") }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}
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.
{{ $opts := dict "silenceDependencyDeprecations" true }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}
sourceMapIncludeSources
(bool) Whether to embed sources in the generated source map. Default is false.
{{ $opts := dict
  "enableSourceMap" true
  "sourceMapIncludeSources" true
}}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}
targetPath
(string) The target path of the resource, relative to the public directory. If unset, the target path defaults to the asset’s original path with a .css extension.
{{ $opts := dict "targetPath" "css/bundle.css" }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}
transpiler
(string) The transpiler to use. The only supported value is dartsass. To install Dart Sass, see the installation instructions. Default is dartsass.

New in v0.170.0

The embedded LibSass transpiler was removed, and setting this option to libsass returns an error. To migrate, set this option to dartsass or remove it.

{{ $opts := dict "transpiler" "dartsass" }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}
vars
(map) A map of key-value pairs used to generate Sass variables. The css.Sass function injects these variables into the stylesheet when it encounters the hugo:vars internal identifier within a @use or @import statement.
{{ $vars := dict
  "font-family" "\"Times New Roman\", Times, serif"
  "font-size" "24px"
  "primary-color" "blue"
}}
{{ $opts := dict "vars" $vars }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}

In the example above, using the identifier in your stylesheet allows you to access the values as Sass variables in the hugo:vars namespace:

@use 'hugo:vars' as v;

.element {
  color: v.$primary-color;
  font-family: v.$font-family;
  font-size: v.$font-size;
}

The above produces output equivalent to:

.element {
  color: blue;
  font-family: "Times New Roman", Times, serif;
  font-size: 24px;
}
New in v0.161.0

The map may optionally contain nested maps. Each nested map is exposed as a separate hugo:vars/<name> namespace, where <name> is the key of the nested map (lowercased). Top-level scalar values and nested maps are independent. A top-level @use 'hugo:vars' only includes scalar values, while @use 'hugo:vars/<name>' only includes the scalars from the named nested map.

{{ $vars := dict
  "font-family" "\"Times New Roman\", Times, serif"
  "font-size" "24px"
  "primary-color" "blue"
  "mobile" (dict
    "font-size" "12px"
    "primary-color" "red"
  )
}}
{{ $opts := dict "vars" $vars }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}

In the stylesheet, reference each nested namespace with a separate @use statement. Assign an alias to access the variables from that namespace:

@use 'hugo:vars' as v;
@use 'hugo:vars/mobile' as mobile;

body {
  color: v.$primary-color;
  font-family: v.$font-family;
  font-size: v.$font-size;
}

@media (max-width: 650px) {
  body {
    color: mobile.$primary-color;
    font-size: mobile.$font-size;
  }
}

The above produces output equivalent to:

body {
  color: blue;
  font-family: "Times New Roman", Times, serif;
  font-size: 24px;
}

@media (max-width: 650px) {
  body {
    color: red;
    font-size: 12px;
  }
}

The vars option is useful for setting Sass variables within your project configuration.

params:
  theme:
    style:
      font-family: '"Times New Roman", Times, serif'
      font-size: 24px
      mobile:
        font-size: 12px
        primary-color: red
      primary-color: blue
[params]
  [params.theme]
    [params.theme.style]
      font-family = '"Times New Roman", Times, serif'
      font-size = '24px'
      primary-color = 'blue'
      [params.theme.style.mobile]
        font-size = '12px'
        primary-color = 'red'
{
   "params": {
      "theme": {
         "style": {
            "font-family": "\"Times New Roman\", Times, serif",
            "font-size": "24px",
            "mobile": {
               "font-size": "12px",
               "primary-color": "red"
            },
            "primary-color": "blue"
         }
      }
   }
}
{{ $opts := dict "vars" site.Params.theme.style }}
{{ $r := resources.Get "sass/main.scss" | css.Sass $opts }}

When passing a vars map to the css.Sass function, Hugo detects common typed CSS values such as 24px or #FF0000 using regular expression matching. If necessary, you can bypass automatic type inference by using the css.Quoted or css.Unquoted function to explicitly indicate a value’s type.

Example

{{ with resources.Get "sass/main.scss" }}
  {{ $opts := dict
    "enableSourceMap" hugo.IsDevelopment
    "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
    "targetPath" "css/main.css"
    "vars" site.Params.styles
    "includePaths" (slice "node_modules/bootstrap/scss")
  }}
  {{ with . | css.Sass $opts }}
    {{ if hugo.IsDevelopment }}
      <link rel="stylesheet" href="{{ .RelPermalink }}">
    {{ else }}
      {{ with . | fingerprint }}
        <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

File system access

Hugo limits the files that this function can import from outside the assets directory to the paths in security.node.permissions.allowRead. By default, this is the project directory, including its node_modules directory. To import files from other locations, such as the node_modules directory of a parent directory in a monorepo, add those paths to the list.

Dart Sass

Hugo uses Dart Sass to transpile Sass to CSS. Install Dart Sass in your development and production environments. If you install Hugo as a Snap package, you do not need to install Dart Sass because the Hugo Snap package includes it.

Development environment

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

OSPackage managerSiteInstallation
LinuxHomebrewbrew.shbrew install sass/sass/sass
LinuxSnapsnapcraft.iosudo snap install dart-sass
macOSHomebrewbrew.shbrew install sass/sass/sass
WindowsChocolateychocolatey.orgchoco install sass
WindowsScoopscoop.shscoop install sass

You may also install prebuilt binaries for Linux, macOS, and Windows. You must install the prebuilt binary outside of your project directory and ensure its path is included in your system’s PATH environment variable.

Run hugo env to list the active transpilers.

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

Production environment

To use Dart Sass with Hugo on a CI/CD platform, you typically must modify your build workflow to install Dart Sass before the Hugo site build begins. This is because these platforms don’t have Dart Sass pre-installed, and Hugo needs it to process your Sass files.

There’s one key exception where you can skip this step: you have committed your resources directory to your repository. This is only possible if:

  • You have not changed Hugo’s default asset cache location.
  • You have not set useResourceCacheWhen to never in your project configuration.

By committing the resources directory, you’re providing the pre-built CSS files directly to your CI/CD platform, so it doesn’t need to run the Sass compilation itself.

For examples of how to install Dart Sass in a production environment, see the hosting guides for CI/CD platforms.