Provide clear documentation for Dart Sass installation, configuration, and usage

[jmooring]

See gohugoio/hugo#8299 (comment)

Ref: https://discourse.gohugo.io/t/first-stable-release-of-dart-sass-embedded/36911/2

[Kissaki]

Current Sass docs link for reference

What scope and place would you like Sass setup docs to have? A short section at the beginning of that page? A separate page with a lot of optional details?

I feel like short setup notes would be helpful and reasonable. But I don’t think extensive configuration or usage of sass itself is in scope for Hugo.

So what are you looking for in configuration and usage beyond what is already documented?

[jmooring]

This isn't actionable at the moment. If we add something to the docs at some point, it would be somewhere else.

We have a broad spectrum of users, from those have never used the command line, to those who build everything from source. Inexperienced users sometimes have trouble modifying their PATH environment variable, but I don't think it is our job to teach them. I recently removed this from the Hugo installation documentation, for very good reasons, replacing it with:

Please consult your operating system documentation if you need help setting file permissions or modifying your PATH environment variable.

For inexperienced users, using a package manager is easier, assuming they can install a package manager. Ideally there would be dart-sass-embedded community packages (not created or maintained by the Hugo developers) for:

Package manager	OS	Status	Site	Installation
Chocolatey	Windows	✔️	chocolatey.org	choco install dart-sass-embedded
Scoop	Windows	✔️	scoop.sh	scoop install dart-sass-embedded
Snap1	Linux	✔️	snapcraft.io	sudo snap install dart-sass-embedded
Homebrew	macOS, Linux	✔️	brew.sh	brew install sass/sass/dart-sass-embedded
MacPorts	macOS	Possible 2

Note that the Hugo Snap package already includes dart-sass-embedded. Once the dart-sass-embedded packages for Chocolately and Scoop are approved and tested in the wild, it will be trivial to add these to the corresponding Hugo packages as dependencies.

Related article by @brycewray:
https://www.brycewray.com/posts/2022/05/using-dart-sass-hugo-nitty-gritty/

Footnotes

1. If snapd is already installed (true on all Ubuntu flavors) and users try to install with sudo apt install dart-sass-embedded, they will be guided to the snap installation. ↩

2. Binaries via download seem to be acceptable. See details. I am not a macOS user; someone else will need to take this on. ↩

[merchako]

Thank you for the work you've done creating installers for Snap, Chocolatey, and Scoop, @jmooring. I agree that there's only so much that can be communicated in a ReadMe.

Inexperienced users sometimes have trouble modifying their PATH environment variable, but I don't think it is our job to teach them.

There are some particulars about installing and configuring Embedded Dart Sass that were exceptionally unintuitive even for more experienced developers, that

1. Dart Sass Embedded is completely different from other Dart Sass packages when it comes to solving their Hugo problems, and
2. Users must add the sass_embedded/ to their path, not just its containing folder.

export PATH="$HOME/bin:$PATH"
export PATH="$HOME/bin/sass_embedded:$PATH"

I was only able to work out this detail thanks to Bryce Wray's articles.

This is the chain of Hugo documentation that I believe most likely for user who notice their need for Dart Sass Embedded:

1. Hugo Pips Docs on Sass
2. "You need to download a release binary from Embedded Dart Sass and make sure it’s in your PC’s $PATH"
3. Embedded Dart Sass release page has no instructions for installation, so go to Readme
4. Readme has no installation or configuration instructions, but it links to the Dart Sass page on the Sass website
5. Sass website has installation instructions for completely different packages, as well as to Sass Embedded on NPM

With a lack of any installation instructions in that chain, it's likely users will get confused, maybe google and wind up who knows where, try to install a different Sass package, or try to install the Node package.

[merchako]

Homebrew now has a dart-sass-embedded formula. (See completed issue).

Package manager	OS	Status	Installation
Chocolatey	Windows	Pending approval 1	chocolatey.org
Scoop	Windows	✔️	scoop.sh
Snap	Linux	✔️	snapcraft.io
Homebrew	macOS, Linux	✔️
MacPorts	macOS	Possible 3

[jmooring]

Temporary documentation here:
https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878

[jmooring]

This will ultimately change with gohugoio/hugo#11059.

[jmooring]

Embedded Dart Sass was deprecated in favor of Dart Sass. Hugo v0.114.0 and later are compatible with both Dart Sass (v1.63.4 and later) and Embedded Dart Sass (v1.62.1 and earlier).

To install Dart Sass:

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.

[bep]

@jmooring that table is great. A foot note: I haven't checked, but I was also hoping that this move also would get the dart binary into the build setups of the most popular build hosts (e.g. Netlify, SASS_VERSION=v1.63.4), but there's probably some more plough work to be done there.

[brycewray]

@bep @jmooring I've been talking to the Cloudflare Pages folks about that, since their new "v2" build image already has EMBEDDED_DART_SASS_VERSION (also at my request for Hugo users). I am told that, within the next couple of weeks, they'll also add DART_SASS_VERSION to accommodate the new packaging.

https://discord.com/channels/595317990191398933/1110589273549328485/1120739643235782826