ASSET MANAGEMENT

ToCSS

用法

使用 Hugo 擴展版和擴展/部署版本中包含的 LibSass 轉譯器，或安裝 Dart Sass（詳見 Dart Sass）以使用 Sass 語言的最新功能來將 Sass 轉譯為 CSS。

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

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

選項

transpiler
(string) 使用的轉譯器，默認為 libsass，也可以選擇 dartsass。Hugo 的擴展版和擴展/部署版本包含了 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 擴展版包含 LibSass 來將 Sass 轉譯為 CSS。2020 年，Sass 團隊已停止支援 LibSass，並推薦使用 Dart Sass。

為了使用 Sass 語言的最新功能，請在開發和生產環境中安裝 Dart Sass。

安裝概覽

Dart Sass 與 Hugo v0.114.0 及更高版本兼容。

如果您之前在 Hugo v0.113.0 及更早版本中使用了內嵌 Dart Sass1，請卸載內嵌 Dart Sass，再安裝 Dart Sass。如果兩者都安裝了，Hugo 會使用 Dart Sass。

如果您安裝 Hugo 為 Snap 套件，則無需額外安裝 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: 安裝 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 轉譯，請在傳遞給 css.Sass 的選項映射中將 transpiler 設置為 dartsass。例如：

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

其他

如果您從源碼編譯 Hugo，並運行 mage test -v，如果您安裝了 Dart Sass 作為 Snap 套件，測試將會失敗。這是因為 Snap 套件的嚴格封閉模型。

  1. 2023 年，Sass 團隊已停止支援內嵌 Dart Sass，並推薦使用 Dart Sass。 ↩︎

  2. 如果（a）您未修改資源快取位置，（b）您未在 網站配置 中設置 useResourceCacheWhen 為 never，以及（c）您將資源目錄添加並提交到您的代碼庫，則無需執行此操作。 ↩︎

文檔貢獻指南 基本使用