ToCSS

语法

css.Sass [OPTIONS] RESOURCE

resource.Resource

别名

toCSS

用法

使用 Hugo 扩展版和扩展/部署版中包含的 LibSass 转译器将 Sass 转译为 CSS，或者安装 Dart Sass 以使用 Sass 语言的最新功能。

{{ $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）如果未设置，转换后的资源的 target path 将是资产文件的原始路径，其扩展名替换为 .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。

通过在开发和生产环境中安装 Dart Sass 来使用 Sass 语言的最新功能。

安装概述

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

如果您一直在 Hugo v0.113.0 及更早版本中使用 Embedded Dart Sass¹，请卸载 Embedded Dart Sass，然后安装 Dart Sass。如果您同时安装了两者，Hugo 将使用 Dart Sass。

如果您将 Hugo 安装为Snap 包，则无需安装 Dart Sass。Hugo Snap 包包含 Dart Sass。

在开发环境中安装

当您将 Dart Sass 安装在 PATH 中的某个位置时，Hugo 将找到它。

操作系统	包管理器	Site	安装
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 Sass²。某些提供商允许您使用上述的软件包管理器之一，或者您可以下载并提取预构建的二进制文件之一。

GitHub Pages

要在 GitHub Pages 上为您的构建安装 Dart Sass，请将此步骤添加到 GitHub Pages 工作流程文件中

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

如果您是首次将 GitHub Pages 用于您的存储库，GitHub 会提供一个包含 Dart Sass 的 Hugo 启动工作流程。这是入门的最简单方法。

GitLab Pages

要在 GitLab Pages 上为您的构建安装 Dart Sass，.gitlab-ci.yml 文件应如下所示

variables:
  HUGO_VERSION: 0.141.0
  DART_SASS_VERSION: 1.83.4
  GIT_DEPTH: 0
  GIT_STRATEGY: clone
  GIT_SUBMODULE_STRATEGY: recursive
  TZ: America/Los_Angeles
image:
  name: golang:1.20-buster
pages:
  script:
    # Install 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*
    # Install 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
    # Build
    - 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.141.0"
DART_SASS_VERSION = "1.83.4"
NODE_VERSION = "22"
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 软件包的严格限制模型所致。

在 2023 年，Sass 团队弃用了 Embedded Dart Sass，转而支持 Dart Sass。 ↩︎
如果 (a) 您没有修改资产缓存位置，并且 (b) 您没有在您的站点配置中将 useResourceCacheWhen 设置为 never，并且 (c) 您将您的 resources 目录添加并提交到您的存储库，则您不必这样做。 ↩︎

用法

选项