resources.ToCSS

{{ with resources.Get "sass/main.scss" }}
  {{ $opts := dict "transpiler" "libsass" "targetPath" "css/style.css" }}
  {{ with . | toCSS $opts }}
    {{ if hugo.IsDevelopment }}
      <link rel="stylesheet" href="{{ .RelPermalink }}">
    {{ else }}
      {{ with . | minify | fingerprint }}
        <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

使用 Hugo extended 和 extended/deploy 版本內建的 LibSass 轉譯器將 Sass 轉譯為 CSS，或安裝 Dart Sass以使用 Sass 語言的最新功能。

Sass 有兩種語法形式：SCSS 和 縮排式。Hugo 支援兩者。

選項

transpiler
(string) 使用的轉譯器，可為 libsass（預設）或 dartsass。Hugo 的 extended 和 extended/deploy 版本內建 LibSass 轉譯器。如需使用 Dart Sass 轉譯器，請參閱以下安裝指引。
targetPath
(string) 如果未設定，轉換後資源的目標路徑將為資產檔案的原始路徑，其副檔名將被替換為 .css。
vars
(map) 一個鍵值對的映射，會在 hugo:vars 命名空間中可用。可用於從 Hugo 模板初始化 Sass 變數。
// LibSass
@import "hugo:vars";

// Dart Sass
@use "hugo:vars" as v;
outputStyle
(string) LibSass 可用的輸出樣式包括 nested（預設）、expanded、compact 和 compressed。Dart Sass 可用的輸出樣式包括 expanded（預設）和 compressed。
precision
(int) 浮點數運算的精確度。不適用於 Dart Sass。
enableSourceMap
(bool) 如果設定為 true，會生成來源地圖。
sourceMapIncludeSources
(bool) 如果設定為 true，會將來源嵌入生成的來源地圖中。不適用於 LibSass。
includePaths
(slice) 一組相對於專案根目錄的路徑，轉譯器在解析 @use 和 @import 語句時會使用這些路徑。
{{ $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 }}
  <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}

Dart Sass

Hugo 的 extended 版本內建 LibSass，可將 Sass 轉譯為 CSS。在 2020 年，Sass 團隊宣布棄用 LibSass，改用 Dart Sass。

透過在開發和生產環境中安裝 Dart Sass，即可使用 Sass 語言的最新功能。

安裝概述

Dart Sass 與 Hugo v0.114.0 及更新版本相容。

如果您在使用 Hugo v0.113.0 及更早版本時使用了嵌入式 Dart Sass1，請先卸載嵌入式 Dart Sass，然後安裝 Dart Sass。如果兩者都已安裝，Hugo 會使用 Dart Sass。

如果您以 Snap 套件 安裝 Hugo，則無需另外安裝 Dart Sass，因為 Hugo Snap 套件內含 Dart Sass。

在開發環境中安裝

當您將 Dart Sass 安裝於 PATH 中的某個位置時，Hugo 會自動找到它。

作業系統 套件管理器 網站 安裝指令
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

您也可以為 Linux、macOS 和 Windows 安裝預編譯二進位檔。

執行 hugo env 列出活動的轉譯器。

在生產環境中安裝

針對 CI/CD 部署（例如 GitHub Pages、GitLab Pages、Netlify 等），您必須編輯工作流程，在 Hugo 建置網站前安裝 Dart Sass2。某些提供者允許您使用上述套件管理器之一，或者您可以下載並解壓縮預編譯二進位檔。

GitHub Pages

要在 GitHub Pages 的建置過程中安裝 Dart Sass，請在 GitHub Pages 工作流程檔案中新增以下步驟：

- name: Install Dart Sass
  run: sudo snap install dart-sass

如果您首次在版本庫中使用 GitHub Pages，GitHub 提供了一個包含 Dart Sass 的 入門工作流程。這是最簡單的入門方式。

GitLab Pages

要在 GitLab Pages 的建置過程中安裝 Dart Sass，.gitlab-ci.yml 檔案應如下所示：

variables:
  HUGO_VERSION: 0.137.1
  DART_SASS_VERSION: 1.80.6
  GIT_DEPTH: 0
  GIT_STRATEGY: clone
  GIT_SUBMODULE_STRATEGY: recursive
  TZ: America/Los_Angeles
image:
  name: golang:1.20-buster
pages:
  script:
    # 安裝 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*
    # 安裝 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
    # 建置
    - hugo --gc --minify
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Netlify

要在 Netlify 的建置過程中安裝 Dart Sass，netlify.toml 檔案應如下所示：

[build.environment]
HUGO_VERSION = "0.137.1"
DART_SASS_VERSION = "1.80.6"
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 \
  """

範例

要使用 Dart Sass 進行轉譯，請在傳遞給 resources.ToCSS 的選項映射中將 transpiler 設為 dartsass。例如：

{{ with resources.Get "sass/main.scss" }}
  {{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }}
  {{ with . | toCSS $opts }}
    {{ if hugo.IsDevelopment }}
      <link rel="stylesheet" href="{{ .RelPermalink }}">
    {{ else }}
      {{ with . | minify | fingerprint }}
        <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

其他事項

如果您從原始碼建置 Hugo 並執行 mage test -v，若您以 Snap 套件方式安裝 Dart Sass，測試會失敗。這是由於 Snap 套件的嚴格限制模式所致。

  1. 在 2023 年，Sass 團隊宣布棄用嵌入式 Dart Sass，改用 Dart Sass。 ↩︎

  2. 若符合以下條件，則不必這麼做：(a) 您未修改資產快取位置，且 (b) 您未在網站設定檔中將 useResourceCacheWhen 設為 never，且 (c) 您已將資源目錄新增並提交到您的版本庫。 ↩︎

ResourceType resources.PostProcess