diff --git a/content/en/functions/css/Sass.md b/content/en/functions/css/Sass.md index 80f828dd54..0d5f98f8ba 100644 --- a/content/en/functions/css/Sass.md +++ b/content/en/functions/css/Sass.md @@ -19,14 +19,19 @@ toc: true ```go-html-template {{ with resources.Get "sass/main.scss" }} - {{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }} + {{ $opts := dict + "enableSourceMap" (not hugo.IsProduction) + "outputStyle" (cond hugo.IsProduction "compressed" "expanded") + "targetPath" "css/main.css" + "transpiler" "libsass" + }} {{ with . | toCSS $opts }} - {{ if hugo.IsDevelopment }} - - {{ else }} - {{ with . | minify | fingerprint }} + {{ if hugo.IsProduction }} + {{ with . | fingerprint }} {{ end }} + {{ else }} + {{ end }} {{ end }} {{ end }} @@ -200,14 +205,19 @@ To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map p ```go-html-template {{ with resources.Get "sass/main.scss" }} - {{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }} + {{ $opts := dict + "enableSourceMap" (not hugo.IsProduction) + "outputStyle" (cond hugo.IsProduction "compressed" "expanded") + "targetPath" "css/main.css" + "transpiler" "dartsass" + }} {{ with . | toCSS $opts }} - {{ if hugo.IsDevelopment }} - - {{ else }} - {{ with . | minify | fingerprint }} + {{ if hugo.IsProduction }} + {{ with . | fingerprint }} {{ end }} + {{ else }} + {{ end }} {{ end }} {{ end }} diff --git a/content/en/functions/resources/ToCSS.md b/content/en/functions/resources/ToCSS.md index 0bd66455b6..1ce7d1081b 100644 --- a/content/en/functions/resources/ToCSS.md +++ b/content/en/functions/resources/ToCSS.md @@ -23,14 +23,19 @@ Use [`css.Sass`] instead. ```go-html-template {{ with resources.Get "sass/main.scss" }} - {{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }} + {{ $opts := dict + "enableSourceMap" (not hugo.IsProduction) + "outputStyle" (cond hugo.IsProduction "compressed" "expanded") + "targetPath" "css/main.css" + "transpiler" "libsass" + }} {{ with . | toCSS $opts }} - {{ if hugo.IsDevelopment }} - - {{ else }} - {{ with . | minify | fingerprint }} + {{ if hugo.IsProduction }} + {{ with . | fingerprint }} {{ end }} + {{ else }} + {{ end }} {{ end }} {{ end }} @@ -90,6 +95,9 @@ includePaths {{ end }} ``` +silenceDeprecations +: (`slice`) {{< new-in 0.139.0 >}} 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]. @@ -197,18 +205,23 @@ command = """\ ### Example -To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example: +To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `css.Sass`. For example: ```go-html-template {{ with resources.Get "sass/main.scss" }} - {{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }} + {{ $opts := dict + "enableSourceMap" (not hugo.IsProduction) + "outputStyle" (cond hugo.IsProduction "compressed" "expanded") + "targetPath" "css/main.css" + "transpiler" "dartsass" + }} {{ with . | toCSS $opts }} - {{ if hugo.IsDevelopment }} - - {{ else }} - {{ with . | minify | fingerprint }} + {{ if hugo.IsProduction }} + {{ with . | fingerprint }} {{ end }} + {{ else }} + {{ end }} {{ end }} {{ end }} diff --git a/content/en/hosting-and-deployment/hosting-on-github/index.md b/content/en/hosting-and-deployment/hosting-on-github/index.md index 6c62fb29d0..81d6a4c87a 100644 --- a/content/en/hosting-and-deployment/hosting-on-github/index.md +++ b/content/en/hosting-and-deployment/hosting-on-github/index.md @@ -188,7 +188,7 @@ The example workflow above includes this step, which typically takes 10‑15 You may remove this step if your site, themes, and modules do not transpile Sass to CSS using the [Dart Sass] transpiler. -[Dart Sass]: /hugo-pipes/transpile-sass-to-css/#dart-sass +[Dart Sass]: /functions/css/sass/#dart-sass ## Other resources diff --git a/content/en/hugo-pipes/transpile-sass-to-css.md b/content/en/hugo-pipes/transpile-sass-to-css.md index 18cfcb0caa..918687b173 100644 --- a/content/en/hugo-pipes/transpile-sass-to-css.md +++ b/content/en/hugo-pipes/transpile-sass-to-css.md @@ -7,208 +7,9 @@ keywords: [] menu: docs: parent: hugo-pipes - returnType: resource.Resource weight: 30 weight: 30 -action: - aliases: [toCSS] - returnType: resource.Resource - signatures: ['css.Sass [OPTIONS] RESOURCE'] -toc: true aliases: [/hugo-pipes/transform-to-css/] --- -## Usage - -Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended and extended/deploy editions, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language. - -```go-html-template -{{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }} -{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }} - -{{ end }} -``` - -Sass has two forms of syntax: [SCSS] and [indented]. Hugo supports both. - -[scss]: https://sass-lang.com/documentation/syntax#scss -[indented]: https://sass-lang.com/documentation/syntax#the-indented-syntax - -## 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](#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. - -```go-html-template -{{ $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 }} - -{{ 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[^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. - -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. - -[^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: - -```yaml -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: - -```toml -[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: - -```go-html-template -{{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }} -{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }} - -{{ 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. - -[brew.sh]: https://brew.sh/ -[chocolatey.org]: https://community.chocolatey.org/packages/sass -[ci/cd]: https://en.wikipedia.org/wiki/CI/CD -[dart sass]: https://sass-lang.com/dart-sass -[libsass]: https://sass-lang.com/libsass -[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest -[scoop.sh]: https://scoop.sh/#/apps?q=sass -[site configuration]: /getting-started/configuration/#configure-build -[snap package]: /installation/linux/#snap -[snapcraft.io]: https://snapcraft.io/dart-sass -[starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml +See the [`css.Sass`](/functions/css/sass) function. diff --git a/content/en/installation/_common/01-editions.md b/content/en/installation/_common/01-editions.md index b6fc23c74e..3df52638e9 100644 --- a/content/en/installation/_common/01-editions.md +++ b/content/en/installation/_common/01-editions.md @@ -10,7 +10,7 @@ Encode to the WebP format when [processing images]. You can decode WebP images w [Transpile Sass to CSS] using the embedded LibSass transpiler. You can use the [Dart Sass] transpiler with any edition.|:heavy_check_mark:|:heavy_check_mark: Deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or an Azure Storage container. See [details].|:x:|:heavy_check_mark: -[dart sass]: /hugo-pipes/transpile-sass-to-css/#dart-sass +[dart sass]: /functions/css/sass/#dart-sass [processing images]: /content-management/image-processing/ -[transpile sass to css]: /hugo-pipes/transpile-sass-to-css/ +[transpile sass to css]: /functions/css/sass/ [details]: /hosting-and-deployment/hugo-deploy/ diff --git a/content/en/installation/_common/02-prerequisites.md b/content/en/installation/_common/02-prerequisites.md index 65ec2a12f2..f27d9d56bf 100644 --- a/content/en/installation/_common/02-prerequisites.md +++ b/content/en/installation/_common/02-prerequisites.md @@ -29,7 +29,7 @@ Please refer to the relevant documentation for installation instructions: [cloudcannon]: https://cloudcannon.com/ [cloudflare pages]: https://pages.cloudflare.com/ -[dart sass install]: /hugo-pipes/transpile-sass-to-css/#dart-sass +[dart sass install]: /functions/css/sass/#dart-sass [dart sass]: https://sass-lang.com/dart-sass [git install]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git [git]: https://git-scm.com/