Using Dart Sass with Hugo: the nitty-gritty

Important note, 2023-06-20: There has been a breaking change in how Embedded Dart Sass is packaged, and Hugo 0.114.0 is the first version that supports the new packaging, which uses the Dart Sass package. I have revised this post’s instructions for Hugo 0.114.0 and newer. If forced to use an older version of Hugo, you must continue with the older, archived Embedded Dart Sass packaging and the former versions of the instructions, which you can find in this page’s history.

Also: while these instructions are about installing a prebuilt Sass binary, please note that you may find it considerably more convenient to use a package manager, instead, as explained in this comprehensive post by Joe Mooring on the Hugo Discourse forum. (I personally prefer installing a prebuilt binary, mainly because I’d rather not wait for a package manager to update its repository whenever there’s a new release of the binary — but, if that doesn’t concern you, you’ll likely prefer using a package manager.)

Some of the responses I got to my recent post, “Using Dart Sass with Hugo: the GitHub Actions edition,” made it clear that there needs to be a one-stop guide that tells how to set up the Dart Sass binary in the PATH on one’s local machine for use with the Hugo static site generator (SSG).

So let’s take care of that right now, shall we?

Introduction

There are four tasks to perform, the first of which you should need to do only once:

Create a bin folder in your user directory and add it (and a designated subfolder-to-come) to your system PATH.
Download/unpack the Dart Sass archive file.
Move the resulting dart-sass folder — the aforementioned “subfolder-to-come” — to the bin folder.
Confirm that the system detects the dart-sass folder as being in the PATH.

With that established, let’s break this up into three sections that you can toggle to expand or compress so you’ll be looking at only what applies to you and your OS/device combo.

Note from the future: The reason we’ll be adding both bin and bin/dart-sass to the PATH is so that, if you also like to download and install the Hugo binary rather than depending on a package manager (e.g., as explained in my later post, “How I install Hugo”), you can use bin for that purpose. It seems to me that the two installations — the Hugo binary and the Dart Sass binary — are sufficiently akin as to suggest such a method.

Linux

Click/tap here to toggle open/close.

Throughout these instructions, we will pretend that your user name is JohnDoe. Thus, your user directory ({$HOME}) will be /home/JohnDoe/.

Add a folder and subfolder to your `PATH`

Create /home/JohnDoe/bin/ if it doesn’t already exist. This bin folder will be the target folder where you’ll store the contents of the Dart Sass archive file you’ll be getting shortly.
Determine which shell your setup is using, bash or zsh:
```
echo $0
```
This will return either bash or zsh.
Use your preferred terminal-level text editor to open the appropriate file — either /home/JohnDoe/.bashrc or /home/JohnDoe/.zshrc — and add the following lines:
```
export PATH="$HOME/bin:$PATH"
export PATH="$HOME/bin/dart-sass:$PATH"
```
Restart the terminal app, and check that PATH now includes your entries:
```
echo $PATH
```

Get the archive file

Navigate to your default downloads destination, /home/JohnDoe/Downloads/.
To get the latest version of Dart Sass, go to its GitHub releases page and download the corresponding tar.gz archive file for your particular system architecture:
- 64-bit ARM (linux-arm64)
- 32-bit ARM (linux-arm)
- x64 (linux-x64)
- IA-32 (linux-ia32)
To unpack the .tar.gz archive file to retrieve its contents, enter tar -xf followed by the name of the .tar.gz file. (As an alternative, depending on your particular Linux distribution and windows manager, you may also be able to use a GUI to perform this operation.) This will result in a sass_embedded folder, the contents of which will depend on which tar.gz archive file you chose.

Move the `dart-sass` folder to `bin`

Note: If you’ve done this before and already have a dart-sass folder within bin, you do want to delete the existing one in favor of what you’ll be moving below.

Enter the following in your terminal app:

mv $HOME/Downloads/dart-sass $HOME/bin/dart-sass

Confirm `dart-sass` is in the `PATH`

Finally, to confirm that the dart-sass folder and its contents are in the PATH, enter the following in your terminal app:

sass --embedded --version

This will run the sass shell script included in the dart-sass folder. The result should look something like this example from Dart Sass v.1.63.4:

{
  "protocolVersion": "2.1.0",
  "compilerVersion": "1.63.4",
  "implementationVersion": "1.63.4",
  "implementationName": "Dart Sass",
  "id": 0
}

If you get any other kind of response, it means the dart-sass folder isn’t in the PATH, after all, so you’ll have to go back through the procedure and figure out what you missed.

Note: If you get a response that shows a wrong version number in compilerVersion and/or implementationVersion, you apparently haven’t moved over the entire dart-sass folder that you got from unpacking the .tar.gz archive file.

And that’s it. I hope this has spared you some searching. If you encounter errors in any of the above information, please let me know so I can fix it ASAP!

Reminder: In a worst-case scenario in which you can’t get this to work no matter what you do, there’s always the option of using the Node.js Sass package, instead, as I described in the original article in this series. It’s not quite as elegant for Hugo’s purposes, and it definitely is slower than using the Dart Sass binary, but it works.

macOS

Click/tap here to toggle open/close.

Throughout these instructions, we will pretend that your user name is JohnDoe. Thus, your user directory ({$HOME}) will be /Users/JohnDoe/.

Add a folder and subfolder to your `PATH`

Create /Users/JohnDoe/bin/ if it doesn’t already exist. This bin folder will be the target folder where you’ll store the contents of the Dart Sass archive file you’ll be getting shortly.
Determine which shell your setup is using, bash or zsh:
```
echo $0
```
This will return either bash or zsh.
Use your preferred terminal-level text editor to open the appropriate file — either /Users/JohnDoe/.bashrc or /Users/JohnDoe/.zshrc — and add the following lines:
```
export PATH="$HOME/bin:$PATH"
export PATH="$HOME/bin/dart-sass:$PATH"
```
Restart the terminal app, and check that PATH now includes your entries:
```
echo $PATH
```

Get the archive file

Navigate to your default downloads destination, /Users/JohnDoe/Downloads/.
To get the latest version of Dart Sass, go to its GitHub releases page and download the corresponding tar.gz archive file for your particular system architecture:
- Apple Silicon (macos-arm64)
- Intel (macos-x64)
To unpack the .tar.gz archive file to retrieve its contents, enter tar -xf followed by the name of the .tar.gz file. (As an alternative, you can double-click the .tar.gz file in the Finder.)
The resulting contents should be as shown inside your downloads folder:
```
dart-sass
└─ dart-sass-embedded
└─ src
		└─ dart
		└─ LICENSE
		└─ sass.snapshot
```
Even though it lacks an extension, dart-sass/sass is a shell script that works with the actual binary, dart-sass/src/dart.

Move the `dart-sass` folder to `bin`

Note: If you’ve done this before and already have a dart-sass folder within bin, you do want to delete the existing one in favor of what you’ll be moving below.

Enter the following in your terminal app:

mv $HOME/Downloads/dart-sass $HOME/bin/dart-sass

Confirm `dart-sass` is in the `PATH`

Finally, to confirm that the dart-sass folder and its contents are in the PATH, enter the following in your terminal app:

sass --embedded --version

This will run the sass shell script included in the sass_embedded folder. The result should look something like this example from Dart Sass v.1.63.4:

{
  "protocolVersion": "2.1.0",
  "compilerVersion": "1.63.4",
  "implementationVersion": "1.63.4",
  "implementationName": "Dart Sass",
  "id": 0
}

If you get any other kind of response, it means the dart-sass folder isn’t in the PATH, after all, so you’ll have to go back through the procedure and figure out what you missed.

And that’s it. I hope this has spared you some searching. If you encounter errors in any of the above information, please let me know so I can fix it ASAP!

Windows

Click/tap here to toggle open/close.

Throughout these instructions, we will pretend that your user name is JohnDoe. Thus, your user directory will be C:\Users\JohnDoe\.

Add a folder and subfolder to your `PATH`

IMPORTANT: Because Windows truncates PATH to 1,024 characters, first open Command Prompt and make a text backup of PATH:
echo %PATH% > C:\path-backup.txt
If you need to restore the PATH later, enter:
set %PATH%=>C:\path-backup.txt

Create C:\Users\JohnDoe\bin\ if it doesn’t already exist. This bin folder will be the target folder where you’ll store the contents of the Dart Sass archive file you’ll be getting shortly.
In the Windows Taskbar search box, search for cmd.
Select the Command Prompt result and click the Run as administrator option.
In Command Prompt, enter:
```
setx PATH "C:\Users\JohnDoe\bin;%PATH%"
```
Close Command Prompt.
Repeat steps 2–3 to reload Command Prompt with Run as administrator again.

In Command Prompt, enter:

setx PATH "C:\Users\JohnDoe\bin\dart-sass;%PATH%"

Repeat step 2–3 to reload Command Prompt (with or without Run as administrator this time) and check the PATH to confirm your new entries are there:
```
echo %PATH%
```

Get the archive file

Navigate to your default downloads destination, C:\Users\JohnDoe\Downloads\.
To get the latest version of Dart Sass, go to its GitHub releases page and download the corresponding tar.gz archive file for your particular system architecture:
- x64 (windows-x64)
- IA-32 (windows-ia32)
In the Windows Taskbar search box, search for cmd.
Open Command Prompt (with or without Run as administrator).
In Command Prompt, enter tar -xf followed by the name of the .tar.gz file.
The resulting contents should be as shown (inside the regular downloads folder):
```
dart-sass
└─ sass.bat
└─ src
		└─ dart.exe
		└─ LICENSE
		└─ sass.snapshot
```
The dart-sass\sass.bat batch file works with the actual binary, dart-sass\src\dart.exe.

Move the `dart-sass` folder to `bin`

Note: If you’ve done this before and already have a dart-sass folder within bin, you do want to delete the existing one in favor of what you’ll be moving below.

Enter the following in Command Prompt:

move C:\Users\JohnDoe\Downloads\dart-sass C:\Users\JohnDoe\bin\dart-sass

Confirm `dart-sass` is in the `PATH`

Finally, to confirm that the dart-sass folder and its contents are in the PATH, enter the following in Command Prompt:

sass --embedded --version

This will run the sass.bat batch file included in the dart-sass folder. The result should look something like this example from Dart Sass v.1.63.4:

{
  "protocolVersion": "2.1.0",
  "compilerVersion": "1.63.4",
  "implementationVersion": "1.63.4",
  "implementationName": "Dart Sass",
  "id": 0
}

If you get any other kind of response, it means the dart-sass folder isn’t in the PATH, after all, so you’ll have to go back through the procedure and figure out what you missed.

And that’s it. I hope this has spared you some searching. If you encounter errors in any of the above information, please let me know so I can fix it ASAP!

References

Zachary Betz, “How to Add a Binary (or Executable, or Program) to Your PATH on macOS, Linux, or Windows” (2021-06-23).
Talha Saif Malik, “How do I know if I have bash or zsh?” (2021-06-06).
“Srini,” “Move files and directories to another location” (2014-01-05).
Apple Support website, “Use zsh as the default shell on your Mac” (2020-01-28).
JavaTpoint website, “Linux Home Directory (retrieved 2022-05-22).
ShellHacks website, “Windows CMD: PATH Variable — Add To PATH — Echo PATH” (2019-04-19).
tar(1) Linux manual page (retrieved 2022-05-22).
TheWindowsClub website, “How to Run Command Prompt as an Administrator in Windows 11/10” (2019-04-18).

Latest commit (ddfbbdb6) for page file:
2023-09-22 at 10:57:57 AM CDT.
Page history

Reply via email

View comments