css.Sass

语法

css.Sass [OPTIONS] RESOURCE

返回值

resource.Resource

别名

toCSS

v0.128.0 中的新功能

{{ 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 扩展版和扩展/部署版中包含的 LibSass 转译器将 Sass 转译为 CSS，或者安装 Dart Sass以使用 Sass 语言的最新功能。

Sass 有两种语法形式：SCSS 和缩进式。Hugo 同时支持这两种形式。

选项

转译器: （字符串）要使用的转译器，可以是 libsass（默认）或 dartsass。Hugo 的扩展版和扩展/部署版包含 LibSass 转译器。要使用 Dart Sass 转译器，请参阅下面的安装说明。
targetPath: （字符串）如果未设置，转换后的资源的 target path 将是原始资产文件的路径，其扩展名被替换为 .css。
vars: （映射）一个键值对映射，它将在 hugo:vars 命名空间中可用。对于从 Hugo 模板初始化 Sass 变量非常有用。

// LibSass
@import "hugo:vars";

// Dart Sass
@use "hugo:vars" as v;

outputStyle: （字符串）LibSass 可用的输出样式包括 nested（默认）、expanded、compact 和 compressed。Dart Sass 可用的输出样式包括 expanded（默认）和 compressed。
precision: （整数）浮点数学的精度。不适用于 Dart Sass。
enableSourceMap: （布尔值）如果为 true，则生成源映射。
sourceMapIncludeSources: （布尔值）如果为 true，则将源嵌入生成的源映射中。不适用于 LibSass。
includePaths: （切片）相对于项目根目录的路径切片，转译器在解析 @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 }}

silenceDeprecations: （切片）v0.139.0 中的新功能用于静默弃用 ID 的切片。弃用 ID 会在警告消息中打印出来，例如 WARN Dart Sass: DEPRECATED [import] ... 中的 “import”。这仅适用于 Dart Sass。

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 将会找到它。

操作系统	包管理器	站点	安装
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。例如

{{ 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，如果将 Dart Sass 作为 Snap 软件包安装，测试将失败。这是因为 Snap 软件包的严格限制模型。

2023 年，Sass 团队弃用了嵌入式 Dart Sass，转而使用 Dart Sass。 ↩︎
如果 (a) 你没有修改资产缓存位置，并且 (b) 你没有在你的站点配置中将 useResourceCacheWhen 设置为 never，并且 (c) 你将你的 resources 目录添加并提交到你的仓库，则无需执行此操作。 ↩︎

选项