ToCSS

Syntax

resources.ToCSS [OPTIONS] RESOURCE

Returns

resource.Resource

Alias

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同时支持两种形式。

Options

transpiler: (string) 要使用的转译器，可以是libsass（默认）或dartsass。Hugo的扩展版包括LibSass转译器。要使用Dart Sass转译器，请参见下面的安装说明。
targetPath: (string) 如果未设置，则转译后的资源的目标路径将是原始资源文件的路径，只是扩展名替换为.css。
vars: (map) 键/值对的映射，将在hugo:vars命名空间中可用。可用于从Hugo模板初始化Sass变量。有关详细信息，请参见Hugo论坛。

// 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。

[Embedded Dart Sass]: Embedded Dart Sass LibSass: https://sass-lang.com/libsass Dart Sass: https://sass-lang.com/dart-sass [Snap软件包]: https://snapcraft.io/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提供了一个[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:
    # 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.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。例如：

{{ $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软件包的严格封闭模型。

如果你未修改资源缓存位置，并且在[站点配置]中没有将useResourceCacheWhen设置为never，并且将资源目录添加到你的代码库并进行了提交，则无需执行此操作。 ↩︎