Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended edition, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language.
Sass has two forms of syntax: [SCSS] and [indented]. Hugo supports both.
: (`string`) The transpiler to use, either `libsass` (default) or `dartsass`. Hugo's extended edition includes the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass) 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](https://discourse.gohugo.io/t/42053/).
```scss
// 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.
The extended version of Hugo includes [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.
[^1]: In 2023, the Sass team deprecated Embedded Dart Sass in favor of 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[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository.
#### GitHub Pages
To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:
```yaml
- 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:
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.
