From fcfb13f18c602905405fe662709b59107b718ab7 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Wed, 21 Jun 2023 21:51:47 -0700 Subject: [PATCH] Add Dart Sass installation and usage documentation Closes #1921 --- content/en/hugo-pipes/transform-to-css.md | 58 ----- .../en/hugo-pipes/transpile-sass-to-css.md | 211 ++++++++++++++++++ content/en/installation/common/01-editions.md | 6 +- .../installation/common/02-prerequisites.md | 36 +-- 4 files changed, 238 insertions(+), 73 deletions(-) delete mode 100644 content/en/hugo-pipes/transform-to-css.md create mode 100644 content/en/hugo-pipes/transpile-sass-to-css.md diff --git a/content/en/hugo-pipes/transform-to-css.md b/content/en/hugo-pipes/transform-to-css.md deleted file mode 100644 index 9af649acbc8..00000000000 --- a/content/en/hugo-pipes/transform-to-css.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: ToCSS -linkTitle: Transpile Sass to SCSS -description: Transpile Sass to CSS. -categories: [asset management] -keywords: [] -menu: - docs: - parent: pipes - weight: 30 -weight: 02 -signature: ["resources.ToCSS RESOURCE [OPTIONS]", "toCSS RESOURCE [OPTIONS]"] ---- - -## Usage - -Any Sass or SCSS file can be transformed into a CSS file using `resources.ToCSS` which takes two arguments, the resource object and a map of options listed below. - -```go-html-template -{{ $sass := resources.Get "sass/main.scss" }} -{{ $style := $sass | resources.ToCSS }} -``` - -### Options - -transpiler [string] - -: The `transpiler` to use, valid values are `libsass` (default) and `dartsass`. If you want to use Hugo with Dart Sass you need to download a release binary from [Embedded Dart Sass](https://github.com/sass/dart-sass-embedded/releases) and make sure it's in your PC's `$PATH` (or `%PATH%` on Windows). - -targetPath [string] -: If not set, the transformed resource's target path will be the asset file original path with its extension replaced by `.css`. - -vars [map] -: Map of key/value pairs that will be available in the `hugo:vars` namespace, e.g. with `@use "hugo:vars" as v;` or (globally) with `@import "hugo:vars";` {{< new-in "0.109.0" >}} - -outputStyle [string] -: Default is `nested` (LibSass) and `expanded` (Dart Sass). Other available output styles for LibSass are `expanded`, `compact` and `compressed`. Dart Sass only supports `expanded` and `compressed`. - -precision [int] -: Precision of floating point math. **Note:** This option is not supported by Dart Sass. - -enableSourceMap [bool] -: When enabled, a source map will be generated. - -sourceMapIncludeSources [bool] -: When enabled, sources will be embedded in the generated source map. (Dart Sass only). {{< new-in "0.108.0" >}} - -includePaths [string slice] -: Additional SCSS/Sass include paths. Paths must be relative to the project directory. - -```go-html-template -{{ $options := (dict "targetPath" "style.css" "outputStyle" "compressed" "enableSourceMap" (not hugo.IsProduction) "includePaths" (slice "node_modules/myscss")) }} -{{ $style := resources.Get "sass/main.scss" | resources.ToCSS $options }} -``` - -{{% note %}} -Setting `outputStyle` to `compressed` will handle Sass/SCSS files minification better than the more generic [`resources.Minify`](/hugo-pipes/minification). -{{% /note %}} diff --git a/content/en/hugo-pipes/transpile-sass-to-css.md b/content/en/hugo-pipes/transpile-sass-to-css.md new file mode 100644 index 00000000000..1e401685f7d --- /dev/null +++ b/content/en/hugo-pipes/transpile-sass-to-css.md @@ -0,0 +1,211 @@ +--- +title: ToCSS +linkTitle: Transpile Sass to SCSS +description: Transpile Sass to CSS. +categories: [asset management] +keywords: [] +menu: + docs: + parent: pipes + weight: 30 +weight: 02 +signature: ["resources.ToCSS RESOURCE [OPTIONS]", "toCSS RESOURCE [OPTIONS]"] +toc: true +aliases: [/hugo-pipes/transform-to-css/] +--- + +## Usage + +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. + +```go-html-template +{{ $options := dict "transpiler" "libsass" "targetPath" "css/style.css" }} +{{ with resources.Get "sass/main.scss" | toCSS $options | 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 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 {{< new-in "0.109.0" >}} +: (`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 included `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 {{< new-in "0.108.0" >}} +: (`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 +{{ $options := 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 $options | minify | fingerprint }} + +{{ end }} +``` + +## Dart Sass + +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. + +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.114.0 + DART_SASS_VERSION: 1.63.5 + 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] +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 && \ + mkdir -p /opt/build/repo/node_modules/.bin && \ + cp -r dart-sass/* /opt/build/repo/node_modules/.bin && \ + rm -rf dart-sass* && \ + hugo --gc --minify \ + """ + +[build.environment] +DART_SASS_VERSION = "1.63.5" +HUGO_VERSION = "0.114.0" +TZ = "America/Los_Angeles" +``` + +### Example + +To tranpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example: + +```go-html-template +{{ $options := dict "transpiler" "dartsass" "targetPath" "css/style.css" }} +{{ with resources.Get "sass/main.scss" | toCSS $options | 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]: https://gohugo.io/getting-started/configuration/#configure-build +[snap package]: https://gohugo.io/installation/linux/#snap +[snapcraft.io]: https://snapcraft.io/dart-sass +[starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml diff --git a/content/en/installation/common/01-editions.md b/content/en/installation/common/01-editions.md index ee9f3ff9376..67e389650e7 100644 --- a/content/en/installation/common/01-editions.md +++ b/content/en/installation/common/01-editions.md @@ -2,7 +2,9 @@ Hugo is available in two editions: standard and extended. With the extended edition you can: -- Encode WebP images (you can decode WebP images with both editions) -- Transpile Sass to CSS using the embedded LibSass transpiler +- Encode WebP images. You can decode WebP images with either edition. +- Transpile Sass to CSS using the legacy LibSass transpiler. The extended edition is not required to use the [Dart Sass] transpiler. We recommend that you install the extended edition. + +[dart sass]: /hugo-pipes/transpile-sass-to-css/#dart-sass diff --git a/content/en/installation/common/02-prerequisites.md b/content/en/installation/common/02-prerequisites.md index 00837082522..0f0772c730f 100644 --- a/content/en/installation/common/02-prerequisites.md +++ b/content/en/installation/common/02-prerequisites.md @@ -1,27 +1,37 @@ ## Prerequisites -Although not required in all cases, Git and Go are often used when working with Hugo. +Although not required in all cases, [Git], [Go], and [Dart Sass] are commonly used when working with Hugo. + Git is required to: -- Use the [Hugo Modules] feature - Build Hugo from source +- Use the [Hugo Modules] feature - Install a theme as a Git submodule - Access [commit information] from a local Git repository -- Host your site with services such as [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify]. +- Host your site with services such as [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify] Go is required to: -- Use the Hugo Modules feature - Build Hugo from source +- Use the Hugo Modules feature + +Dart Sass is required to transpile modern Sass to CSS. + +Please refer to the relevant documentation for installation instructions: -Please refer to the [Git] and [Go] documentation for installation instructions. +- [Git][git install] +- [Go][go install] +- [Dart Sass][dart sass install] -[AWS Amplify]: https://aws.amazon.com/amplify/ -[CloudCannon]: https://cloudcannon.com/ -[Cloudflare Pages]: https://pages.cloudflare.com/ -[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git -[GitHub Pages]: https://pages.github.com/ -[GitLab Pages]: https://docs.gitlab.com/ee/user/project/pages/ -[Go]: https://go.dev/doc/install -[Netlify]: https://www.netlify.com/ +[cloudcannon]: https://cloudcannon.com/ +[cloudflare pages]: https://pages.cloudflare.com/ +[dart sass install]: /hugo-pipes/transpile-sass-to-css/#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/ +[github pages]: https://pages.github.com/ +[gitlab pages]: https://docs.gitlab.com/ee/user/project/pages/ +[go install]: https://go.dev/doc/install +[go]: https://go.dev/ +[netlify]: https://www.netlify.com/