resources.ToCSS

Syntax

resources.ToCSS [OPTIONS] RESOURCE

Returns

resource.Resource

Alias

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

Sass有两种语法形式：[SCSS]和[indented]。Hugo支持两种形式。

[scss]：https://sass-lang.com/documentation/syntax#scss [indented]：https://sass-lang.com/documentation/syntax#the-indented-syntax

选项

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团队推出Dart Sass，取代了LibSass。

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

安装概述

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

如果您以前一直在使用内嵌Dart Sass[^1]和Hugo v0.113.0及更早版本，现在需要卸载内嵌Dart Sass，然后安装Dart Sass。如果两者都安装了，Hugo将使用Dart Sass。

如果您将Hugo安装为[Snap包]，则无需安装Dart Sass。Hugo Snap包已经包含了Dart Sass。

[^1]：在2023年，Sass团队推出Dart Sass，取代了内嵌Dart Sass。

在开发环境中安装

当您在PATH中的某个位置安装Dart Sass后，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[^2]。某些提供商允许您使用上面列出的包管理器之一，或者您可以下载和提取其中一个预编译二进制文件。

[^2]：如果(a)您没有修改资源缓存位置，(b)您没有在[站点配置]中将useResourceCacheWhen设置为never，(c)您将资源目录添加并提交到您的存储库中，则不必执行此操作。

GitHub Pages

要为GitHub Pages上的构建安装Dart Sass，请在GitHub Pages工作流程文件中添加以下步骤：

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

如果您首次使用GitHub Pages并且与存储库一起提供了[Hugo的入门工作流程]，则已包含了Dart Sass。这是最简单的入门方式。

GitLab Pages

要为GitLab Pages上的构建安装Dart Sass，请确保.gitlab-ci.yml文件如下所示：

variables:
  HUGO_VERSION: 0.115.1
  DART_SASS_VERSION: 1.63.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.115.1"
DART_SASS_VERSION = "1.63.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命令，如果您将Dart Sass作为Snap包安装，测试将失败。这是由于Snap包的严格约束模型造成的。

[brew.sh]：https://brew.sh/ [chocolatey.org]：https://community.chocolatey.org/packages/sass [ci/cd]：https://en.wikipedia.org/wiki/CI/CD [dart sass]：https://sass-lang.com/dart-sass [libsass]：https://sass-lang.com/libsass [prebuilt binaries]：https://github.com/sass/dart-sass/releases/latest [scoop.sh]：https://scoop.sh/#/apps?q=sass [site configuration]：https://example.com/getting-started/configuration/#configure-build [snap package]：https://example.com/installation/linux/#snap [snapcraft.io]：https://snapcraft.io/dart-sass [starter workflow]：https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml

See also

Last updated: November 23, 2023: first release (332dc4cd7)
Improve this page