css.Sass
- 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 isfalse.{{ $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@useand@importstatements. 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@useand@importstatements.{{ $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, eitherexpandedorcompressed. Default isexpanded.{{ $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.,importinWARN 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@warnor@debugrules. Default isfalse.{{ $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 isfalse.{{ $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 thepublicdirectory. If unset, the target path defaults to the asset’s original path with a.cssextension.{{ $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 isdartsass. To install Dart Sass, see the installation instructions. Default isdartsass.New in v0.170.0
The embedded LibSass transpiler was removed, and setting this option to
libsassreturns an error. To migrate, set this option todartsassor 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. Thecss.Sassfunction injects these variables into the stylesheet when it encounters thehugo:varsinternal identifier within a@useor@importstatement.{{ $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:varsnamespace:@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:
New in v0.161.0.element { color: blue; font-family: "Times New Roman", Times, serif; font-size: 24px; }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
@usestatement. 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
varsoption 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
varsmap to thecss.Sassfunction, Hugo detects common typed CSS values such as24pxor#FF0000using regular expression matching. If necessary, you can bypass automatic type inference by using thecss.Quotedorcss.Unquotedfunction 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.
| 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. 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
useResourceCacheWhento 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.
