Some of the responses I got to my recent post, “Using Dart Sass with Hugo: GitHub Actions edition,” made it clear that there needs to be a one-stop guide that tells how to set up the Embedded 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 systemPATH
. - Download/unpack the Embedded Dart Sass archive file.
- Move the resulting
sass_embedded
folder — the aforementioned “subfolder-to-come” — to thebin
folder. - Confirm that the system detects the
sass_embedded
folder as being in thePATH
.
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. I have successfully tested these procedures in all three OSs mentioned, using macOS natively and running Linux and Windows in virtual machines.
Note from the future: The reason we’ll be adding both bin
and bin/sass_embedded
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 Embedded 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. Thisbin
folder will be the target folder where you’ll store the contents of the Embedded Dart Sass archive file you’ll be getting shortly.Determine which shell your setup is using,
bash
orzsh
:This will return eitherecho $0
bash
orzsh
.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/sass_embedded:$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 Embedded 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
) - x64 (
linux-x64
) - IA-32 (
linux-ia32
)
- 64-bit ARM (
To unpack the
.tar.gz
archive file to retrieve its contents, entertar -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 asass_embedded
folder, the contents of which will depend on whichtar.gz
archive file you chose.
Move the sass_embedded
folder to bin
Note: If you’ve done this before and already have a sass_embedded
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/sass_embedded $HOME/bin/sass_embedded
Confirm sass_embedded
is in the PATH
Finally, to confirm that the sass_embedded
folder and its contents are in the PATH
, enter the following in your terminal app:
dart-sass-embedded --version
This will run the dart-sass-embedded
shell script included in the sass_embedded
folder. The result should look something like this example from Embedded Dart Sass v.1.52.1:
{
"protocolVersion": "1.0.0",
"compilerVersion": "1.52.1",
"implementationVersion": "1.52.1",
"implementationName": "Dart Sass",
"id": 0
}
If you get any other kind of response, it means the sass_embedded
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 sass_embedded
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 Embedded 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. Thisbin
folder will be the target folder where you’ll store the contents of the Embedded Dart Sass archive file you’ll be getting shortly.Determine which shell your setup is using,
bash
orzsh
:This will return eitherecho $0
bash
orzsh
.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/sass_embedded:$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 Embedded 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
)
- Apple Silicon (
To unpack the
.tar.gz
archive file to retrieve its contents, entertar -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:Even though it lacks an extension,sass_embedded └─ dart-sass-embedded └─ src └─ dart └─ dart-sass-embedded.snapshot └─ LICENSE
sass_embedded/dart-sass-embedded
is a shell script that works with the actual binary,sass_embedded/src/dart
.
Move the sass_embedded
folder to bin
Note: If you’ve done this before and already have a sass_embedded
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/sass_embedded $HOME/bin/sass_embedded
Confirm sass_embedded
is in the PATH
Finally, to confirm that the sass_embedded
folder and its contents are in the PATH
, enter the following in your terminal app:
dart-sass-embedded --version
This will run the dart-sass-embedded
shell script included in the sass_embedded
folder. The result should look something like this example from Embedded Dart Sass v.1.52.1:
{
"protocolVersion": "1.0.0",
"compilerVersion": "1.52.1",
"implementationVersion": "1.52.1",
"implementationName": "Dart Sass",
"id": 0
}
If you get any other kind of response, it means the sass_embedded
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!
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 Embedded Dart Sass binary, but it works.
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. Thisbin
folder will be the target folder where you’ll store the contents of the Embedded 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\sass_embedded;%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 Embedded 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
)
- x64 (
In the Windows Taskbar search box, search for
cmd
.Open
Command Prompt
(with or withoutRun 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):Thesass_embedded └─ dart-sass-embedded.bat └─ src └─ dart.exe └─ dart-sass-embedded.snapshot └─ LICENSE
sass_embedded\dart-sass-embedded.bat
batch file works with the actual binary,sass_embedded\src\dart.exe
.
Move the sass_embedded
folder to bin
Note: If you’ve done this before and already have a sass_embedded
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\sass_embedded C:\Users\JohnDoe\bin\sass_embedded
Confirm sass_embedded
is in the PATH
Finally, to confirm that the sass_embedded
folder and its contents are in the PATH
, enter the following in Command Prompt:
dart-sass-embedded --version
This will run the dart-sass-embedded.bat
batch file included in the sass_embedded
folder. The result should look something like this example from Embedded Dart Sass v.1.52.1:
{
"protocolVersion": "1.0.0",
"compilerVersion": "1.52.1",
"implementationVersion": "1.52.1",
"implementationName": "Dart Sass",
"id": 0
}
If you get any other kind of response, it means the sass_embedded
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!
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 Embedded Dart Sass binary, but it works.
References
- Zachary Betz, “How to Add a Binary (or Executable, or Program) to Your PATH on macOS, Linux, or Windows.”
- Talha Saif Malik, “How do I know if I have bash or zsh?”
- “Srini,” “Move files and directories to another location.”
- Apple Support website, “Use zsh as the default shell on your Mac,” January 28, 2020.
- JavaTpoint website, “Linux Home Directory.”
- ShellHacks website, “Windows CMD: PATH Variable — Add To PATH — Echo PATH.”
- tar(1) Linux manual page.
- TheWindowsClub website, “How to Run Command Prompt as an Administrator in Windows 11/10.”