mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-21 21:35:28 +02:00
Merge commit 'a024bc7d76fcc5e49e8210f9b0896db9ef21861a'
This commit is contained in:
Bjørn Erik Pedersen
@@ -4,14 +4,10 @@ description: Compiles the given JavaScript resource with Babel.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/js/Build
|
||||
- functions/resources/Fingerprint
|
||||
- functions/resources/Minify
|
||||
related: []
|
||||
returnType: resource.Resource
|
||||
signatures: ['resources.Babel [OPTIONS] RESOURCE']
|
||||
toc: true
|
||||
expiryDate: 2025-06-24 # deprecated 2024-06-24
|
||||
expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0
|
||||
---
|
||||
|
||||
{{% deprecated-in 0.128.0 %}}
|
||||
@@ -19,76 +15,3 @@ Use [`js.Babel`] instead.
|
||||
|
||||
[`js.Babel`]: /functions/js/babel/
|
||||
{{% /deprecated-in %}}
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "js/main.js" }}
|
||||
{{ if hugo.IsDevelopment }}
|
||||
{{ with . | babel }}
|
||||
<script src="{{ .RelPermalink }}"></script>
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ $opts := dict "minified" true }}
|
||||
{{ with . | babel $opts | fingerprint }}
|
||||
<script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
Step 1
|
||||
: Install [Node.js](https://nodejs.org/en/download)
|
||||
|
||||
Step 2
|
||||
: Install the required Node.js packages in the root of your project.
|
||||
|
||||
```sh
|
||||
npm install --save-dev @babel/core @babel/cli
|
||||
```
|
||||
|
||||
Step 3
|
||||
: Add the babel executable to Hugo's `security.exec.allow` list in your site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[security.exec]
|
||||
allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Configuration
|
||||
|
||||
We add the main project's `node_modules` to `NODE_PATH` when running Babel and similar tools. There are some known [issues](https://github.com/babel/babel/issues/5618) with Babel in this area, so if you have a `babel.config.js` living in a Hugo Module (and not in the project itself), we recommend using `require` to load the presets/plugins, e.g.:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
require("@babel/preset-env"),
|
||||
{
|
||||
useBuiltIns: "entry",
|
||||
corejs: 3,
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
config
|
||||
: (`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` in your project. More information on these configuration files can be found here: [babel configuration](https://babeljs.io/docs/en/configuration).
|
||||
|
||||
minified
|
||||
: (`bool`) Save as many bytes as possible when printing
|
||||
|
||||
noComments
|
||||
: (`bool`) Write comments to generated output (true by default)
|
||||
|
||||
compact
|
||||
: (`bool`) Do not include superfluous whitespace characters and line terminators. Defaults to `auto` if not set.
|
||||
|
||||
verbose
|
||||
: (`bool`) Log everything
|
||||
|
||||
sourceMap
|
||||
: (`string`) Output `inline` or `external` sourcemap from the babel compile. External sourcemaps will be written to the target with the output file name + ".map". Input sourcemaps can be read from js.Build and node modules and combined into the output sourcemaps.
|
||||
|
||||
@@ -12,7 +12,7 @@ action:
|
||||
|
||||
The `resources.Concat` function returns a concatenated slice of resources, caching the result using the target path as its cache key. Each resource must have the same [media type].
|
||||
|
||||
Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] method.
|
||||
Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] method.
|
||||
|
||||
[media type]: https://en.wikipedia.org/wiki/Media_type
|
||||
[`publish`]: /methods/resource/publish/
|
||||
|
||||
@@ -18,6 +18,15 @@ action:
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< new-in 0.141.0 >}}
|
||||
The `Err` method on the returned resource was removed in v0.141.0.
|
||||
|
||||
Use the [`try`] statement instead, as shown in the [error handling] example below.
|
||||
|
||||
[`try`]: /functions/go-template/try
|
||||
[error handling]: #error-handling
|
||||
{{< /new-in >}}
|
||||
|
||||
```go-html-template
|
||||
{{ $url := "https://example.org/images/a.jpg" }}
|
||||
{{ with try (resources.GetRemote $url) }}
|
||||
@@ -35,6 +44,39 @@ toc: true
|
||||
|
||||
The `resources.GetRemote` function takes an optional map of options.
|
||||
|
||||
###### body
|
||||
|
||||
(`string`) The data you want to transmit to the server.
|
||||
|
||||
###### headers
|
||||
|
||||
(`map[string][]string`) The collection of key-value pairs that provide additional information about the request.
|
||||
|
||||
###### key
|
||||
|
||||
(`string`) The cache key. Hugo derives the default value from the URL and options map. See [caching](#caching).
|
||||
|
||||
###### method
|
||||
|
||||
(`string`) The action to perform on the requested resource, typically one of `GET`, `POST`, or `HEAD`.
|
||||
|
||||
###### responseHeaders
|
||||
{{< new-in 0.143.0 />}}
|
||||
|
||||
(`[]string`) The headers to extract from the server's response, accessible through the resource's [`Data.Headers`] method. Header name matching is case-insensitive.
|
||||
|
||||
[`Data.Headers`]: /methods/resource/data/#headers
|
||||
|
||||
## Options examples
|
||||
|
||||
{{% note %}}
|
||||
For brevity, the examples below do not include [error handling].
|
||||
|
||||
[error handling]: #error-handling
|
||||
{{% /note %}}
|
||||
|
||||
To include a header:
|
||||
|
||||
```go-html-template
|
||||
{{ $url := "https://example.org/api" }}
|
||||
{{ $opts := dict
|
||||
@@ -43,7 +85,7 @@ The `resources.GetRemote` function takes an optional map of options.
|
||||
{{ $resource := resources.GetRemote $url $opts }}
|
||||
```
|
||||
|
||||
If you need multiple values for the same header key, use a slice:
|
||||
To specify more than one value for the same header key, use a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $url := "https://example.org/api" }}
|
||||
@@ -53,7 +95,7 @@ If you need multiple values for the same header key, use a slice:
|
||||
{{ $resource := resources.GetRemote $url $opts }}
|
||||
```
|
||||
|
||||
You can also change the request method and set the request body:
|
||||
To post data:
|
||||
|
||||
```go-html-template
|
||||
{{ $url := "https://example.org/api" }}
|
||||
@@ -65,6 +107,27 @@ You can also change the request method and set the request body:
|
||||
{{ $resource := resources.GetRemote $url $opts }}
|
||||
```
|
||||
|
||||
To override the default cache key:
|
||||
|
||||
```go-html-template
|
||||
{{ $url := "https://example.org/images/a.jpg" }}
|
||||
{{ $opts := dict
|
||||
"key" (print $url (now.Format "2006-01-02"))
|
||||
}}
|
||||
{{ $resource := resources.GetRemote $url $opts }}
|
||||
```
|
||||
|
||||
To extract specific headers from the server's response:
|
||||
|
||||
```go-html-template
|
||||
{{ $url := "https://example.org/images/a.jpg" }}
|
||||
{{ $opts := dict
|
||||
"method" "HEAD"
|
||||
"responseHeaders" (slice "X-Frame-Options" "Server")
|
||||
}}
|
||||
{{ $resource := resources.GetRemote $url $opts }}
|
||||
```
|
||||
|
||||
## Remote data
|
||||
|
||||
When retrieving remote data, use the [`transform.Unmarshal`] function to [unmarshal](g) the response.
|
||||
@@ -139,40 +202,6 @@ The [`Data`] method on a resource returned by the `resources.GetRemote` function
|
||||
|
||||
[`Data`]: /methods/resource/data/
|
||||
|
||||
```go-html-template
|
||||
{{ $url := "https://example.org/images/a.jpg" }}
|
||||
{{ with try (resources.GetRemote $url) }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "%s" . }}
|
||||
{{ else with .Value }}
|
||||
{{ with .Data }}
|
||||
{{ .ContentLength }} → 42764
|
||||
{{ .ContentType }} → image/jpeg
|
||||
{{ .Status }} → 200 OK
|
||||
{{ .StatusCode }} → 200
|
||||
{{ .TransferEncoding }} → []
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %q" $url }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
ContentLength
|
||||
: (`int`) The content length in bytes.
|
||||
|
||||
ContentType
|
||||
: (`string`) The content type.
|
||||
|
||||
Status
|
||||
: (`string`) The HTTP status text.
|
||||
|
||||
StatusCode
|
||||
: (`int`) The HTTP status code.
|
||||
|
||||
TransferEncoding
|
||||
: (`string`) The transfer encoding.
|
||||
|
||||
## Caching
|
||||
|
||||
Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches] for details.
|
||||
@@ -184,7 +213,8 @@ Override the cache key by setting a `key` in the options map. Use this approach
|
||||
```go-html-template
|
||||
{{ $url := "https://example.org/images/a.jpg" }}
|
||||
{{ $cacheKey := print $url (now.Format "2006-01-02") }}
|
||||
{{ $resource := resources.GetRemote $url (dict "key" $cacheKey) }}
|
||||
{{ $opts := dict "key" $cacheKey }}
|
||||
{{ $resource := resources.GetRemote $url $opts }}
|
||||
```
|
||||
|
||||
[configure file caches]: /getting-started/configuration/#configure-file-caches
|
||||
|
||||
@@ -4,15 +4,10 @@ description: Processes the given resource with PostCSS using any PostCSS plugin.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/resources/Fingerprint
|
||||
- functions/resources/Minify
|
||||
- functions/resources/PostProcess
|
||||
- functions/css/Sass
|
||||
related: []
|
||||
returnType: resource.Resource
|
||||
signatures: ['resources.PostCSS [OPTIONS] RESOURCE']
|
||||
toc: true
|
||||
expiryDate: 2025-06-24 # deprecated 2024-06-24
|
||||
expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0
|
||||
---
|
||||
|
||||
{{% deprecated-in 0.128.0 %}}
|
||||
@@ -20,116 +15,3 @@ Use [`css.PostCSS`] instead.
|
||||
|
||||
[`css.PostCSS`]: /functions/css/postcss/
|
||||
{{% /deprecated-in %}}
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "css/main.css" | postCSS }}
|
||||
<link rel="stylesheet" href="{{ .RelPermalink }}">
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
Follow the steps below to transform CSS using any of the available [PostCSS plugins].
|
||||
|
||||
Step 1
|
||||
: Install [Node.js].
|
||||
|
||||
Step 2
|
||||
: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
|
||||
|
||||
```sh
|
||||
npm i -D postcss postcss-cli autoprefixer
|
||||
```
|
||||
|
||||
Step 3
|
||||
: Create a PostCSS configuration file in the root of your project. You must name this file `postcss.config.js` or another [supported file name]. For example:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
require('autoprefixer')
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
{{% include "functions/resources/_common/postcss-windows-warning.md" %}}
|
||||
{{% /note %}}
|
||||
|
||||
Step 4
|
||||
: Place your CSS file within the `assets/css` directory.
|
||||
|
||||
Step 5
|
||||
: Process the resource with PostCSS:
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "css/main.css" | postCSS }}
|
||||
<link rel="stylesheet" href="{{ .RelPermalink }}">
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
The `resources.PostCSS` method takes an optional map of options.
|
||||
|
||||
config
|
||||
: (`string`) The directory that contains the PostCSS configuration file. Default is the root of the project directory.
|
||||
|
||||
noMap
|
||||
: (`bool`) Default is `false`. If `true`, disables inline sourcemaps.
|
||||
|
||||
inlineImports
|
||||
: (`bool`) Default is `false`. Enable inlining of @import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides.
|
||||
|
||||
skipInlineImportsNotFound
|
||||
: (`bool`) Default is `false`. Before Hugo 0.99.0 when `inlineImports` was enabled and we failed to resolve an import, we logged it as a warning. We now fail the build. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set `skipInlineImportsNotFound` to true.
|
||||
|
||||
```go-html-template
|
||||
{{ $opts := dict "config" "config-directory" "noMap" true }}
|
||||
{{ with resources.Get "css/main.css" | postCSS $opts }}
|
||||
<link rel="stylesheet" href="{{ .RelPermalink }}">
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## No configuration file
|
||||
|
||||
To avoid using a PostCSS configuration file, you can specify a minimal configuration using the options map.
|
||||
|
||||
use
|
||||
: (`string`) A space-delimited list of PostCSS plugins to use.
|
||||
|
||||
parser
|
||||
: (`string`) A custom PostCSS parser.
|
||||
|
||||
stringifier
|
||||
: (`string`) A custom PostCSS stringifier.
|
||||
|
||||
syntax
|
||||
: (`string`) Custom postcss syntax.
|
||||
|
||||
```go-html-template
|
||||
{{ $opts := dict "use" "autoprefixer postcss-color-alpha" }}
|
||||
{{ with resources.Get "css/main.css" | postCSS $opts }}
|
||||
<link rel="stylesheet" href="{{ .RelPermalink }}">
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Check environment
|
||||
|
||||
The current Hugo environment name (set by `--environment` or in configuration or OS environment) is available in the Node context, which allows constructs like this:
|
||||
|
||||
```js
|
||||
const autoprefixer = require('autoprefixer');
|
||||
const purgecss = require('@fullhuman/postcss-purgecss');
|
||||
module.exports = {
|
||||
plugins: [
|
||||
autoprefixer,
|
||||
process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
[node.js]: https://nodejs.org/en/download
|
||||
[postcss plugins]: https://www.postcss.parts/
|
||||
[supported file name]: https://github.com/postcss/postcss-load-config#usage
|
||||
[transpile to CSS]: /functions/css/sass/
|
||||
|
||||
@@ -13,33 +13,28 @@ action:
|
||||
toc: true
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ with resources.Get "css/main.css" }}
|
||||
{{ if hugo.IsDevelopment }}
|
||||
<link rel="stylesheet" href="{{ .RelPermalink }}">
|
||||
{{ else }}
|
||||
{{ with . | postCSS | minify | fingerprint | resources.PostProcess }}
|
||||
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
The `resources.PostProcess` function delays resource transformation steps until the build is complete, primarily for tasks like removing unused CSS rules.
|
||||
|
||||
Marking a resource with `resources.PostProcess` postpones transformations until the build has finished.
|
||||
## Example
|
||||
|
||||
Call `resources.PostProcess` when one or more of the steps in the transformation chain depends on the result of the build.
|
||||
In this example, after the build is complete, Hugo will:
|
||||
|
||||
A prime use case for this is purging unused CSS rules using the [PurgeCSS] plugin for the PostCSS Node.js package.
|
||||
1. Purge unused CSS using the [PurgeCSS] plugin for [PostCSS]
|
||||
2. Add vendor prefixes to CSS rules using the [Autoprefixer] plugin for PostCSS
|
||||
3. [Minify] the CSS
|
||||
4. [Fingerprint] the CSS
|
||||
|
||||
## CSS Purging
|
||||
|
||||
{{% note %}}
|
||||
There are several ways to set up CSS purging with PostCSS in Hugo. If you have a simple project, you should consider going the simpler route and drop the use of `resources.PostProcess` and just extract keywords from the templates. See the [Tailwind documentation](https://tailwindcss.com/docs/controlling-file-size/#app) for examples.
|
||||
{{% /note %}}
|
||||
[autoprefixer]: https://github.com/postcss/autoprefixer
|
||||
[fingerprint]: /functions/resources/fingerprint/
|
||||
[minify]: /functions/resources/minify/
|
||||
[postcss]: /functions/css/postcss/
|
||||
[purgecss]: https://purgecss.com/plugins/postcss.html
|
||||
|
||||
Step 1
|
||||
: Install [Node.js].
|
||||
|
||||
[node.js]: https://nodejs.org/en/download
|
||||
|
||||
Step 2
|
||||
: Install the required Node.js packages in the root of your project:
|
||||
|
||||
@@ -48,11 +43,27 @@ npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss
|
||||
```
|
||||
|
||||
Step 3
|
||||
: Create a PostCSS configuration file in the root of your project. You must name this file `postcss.config.js` or another [supported file name]. For example:
|
||||
: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`].
|
||||
|
||||
```js
|
||||
[`config/production`]: /getting-started/configuration/#configuration-directory
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[build.buildStats]
|
||||
enable = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
See the [configure build] documentation for details and options.
|
||||
|
||||
[configure build]: /getting-started/configuration/#configure-build
|
||||
|
||||
Step 4
|
||||
: Create a PostCSS configuration file in the root of your project.
|
||||
|
||||
{{< code file="postcss.config.js" copy=true >}}
|
||||
const autoprefixer = require('autoprefixer');
|
||||
const purgecss = require('@fullhuman/postcss-purgecss')({
|
||||
const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default;
|
||||
|
||||
const purgecss = purgeCSSPlugin({
|
||||
content: ['./hugo_stats.json'],
|
||||
defaultExtractor: content => {
|
||||
const els = JSON.parse(content).htmlElements;
|
||||
@@ -68,26 +79,16 @@ const purgecss = require('@fullhuman/postcss-purgecss')({
|
||||
|
||||
module.exports = {
|
||||
plugins: [
|
||||
process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
|
||||
autoprefixer,
|
||||
process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null
|
||||
]
|
||||
};
|
||||
```
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
{{% include "functions/resources/_common/postcss-windows-warning.md" %}}
|
||||
{{% /note %}}
|
||||
|
||||
Step 4
|
||||
: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`].
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[build.buildStats]
|
||||
enable = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
See the [configure build] documentation for details and options.
|
||||
|
||||
Step 5
|
||||
: Place your CSS file within the `assets/css` directory.
|
||||
|
||||
@@ -108,10 +109,10 @@ Step 6
|
||||
|
||||
## Environment variables
|
||||
|
||||
Hugo passes these environment variables to PostCSS, which allows you to do something like:
|
||||
Hugo passes the environment variables below to PostCSS, allowing you to do something like:
|
||||
|
||||
```js
|
||||
process.env.HUGO_ENVIRONMENT === 'production' ? [autoprefixer] : []
|
||||
process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
|
||||
```
|
||||
|
||||
PWD
|
||||
@@ -122,16 +123,16 @@ HUGO_ENVIRONMENT
|
||||
Default is `production` for `hugo` and `development` for `hugo server`.
|
||||
|
||||
HUGO_PUBLISHDIR
|
||||
: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this directory from PostCSS when running the server, you could run the server with one of these flags:
|
||||
: The absolute path to the publish directory, typically `public`. This value points to a directory on disk, even when rendering to memory with the `--renderToMemory` command line flag.
|
||||
|
||||
```sh
|
||||
hugo server --renderToDisk
|
||||
hugo server --renderStaticToDisk
|
||||
```
|
||||
HUGO_FILE_X
|
||||
: Hugo automatically mounts the following files from your project's root directory under `assets/_jsconfig`:
|
||||
|
||||
Also, Hugo will add environment variables for all files mounted below `assets/_jsconfig`. A default mount will be set up with files in the project root matching this regexp: `(babel|postcss|tailwind)\.config\.js`.
|
||||
- `babel.config.js`
|
||||
- `postcss.config.js`
|
||||
- `tailwind.config.js`
|
||||
|
||||
These will get environment variables named on the form `HUGO_FILE_:filename:` where `:filename:` is all upper case with periods replaced with underscore. This allows you to do something like:
|
||||
For each file, Hugo creates a corresponding environment variable named `HUGO_FILE_:filename:`, where `:filename:` is the uppercase version of the filename with periods replaced by underscores. This allows you to access these files within your JavaScript, for example:
|
||||
|
||||
```js
|
||||
let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js';
|
||||
@@ -150,9 +151,3 @@ You cannot manipulate the values returned from the resource’s methods. For exa
|
||||
{{ $css = $css | css.PostCSS | minify | fingerprint | resources.PostProcess }}
|
||||
{{ $css.RelPermalink | strings.ToUpper }}
|
||||
```
|
||||
|
||||
[node.js]: https://nodejs.org/en/download
|
||||
[supported file name]: https://github.com/postcss/postcss-load-config#usage
|
||||
[`config/production`]: /getting-started/configuration/#configuration-directory
|
||||
[configure build]: /getting-started/configuration/#configure-build
|
||||
[purgecss]: https://github.com/FullHuman/purgecss#readme
|
||||
|
||||
@@ -4,15 +4,10 @@ description: Transpiles Sass to CSS.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
related:
|
||||
- functions/resources/Fingerprint
|
||||
- functions/resources/Minify
|
||||
- functions/css/PostCSS
|
||||
- functions/resources/PostProcess
|
||||
related: []
|
||||
returnType: resource.Resource
|
||||
signatures: ['resources.ToCSS [OPTIONS] RESOURCE']
|
||||
toc: true
|
||||
expiryDate: 2025-06-24 # deprecated 2024-06-24
|
||||
expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0
|
||||
---
|
||||
|
||||
{{% deprecated-in 0.128.0 %}}
|
||||
@@ -20,212 +15,3 @@ Use [`css.Sass`] instead.
|
||||
|
||||
[`css.Sass`]: /functions/css/sass/
|
||||
{{% /deprecated-in %}}
|
||||
|
||||
```go-html-template
|
||||
{{ 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 }}
|
||||
```
|
||||
|
||||
Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended and extended/deploy editions, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language.
|
||||
|
||||
Sass has two forms of syntax: [SCSS] and [indented]. Hugo supports both.
|
||||
|
||||
[scss]: https://sass-lang.com/documentation/syntax#scss
|
||||
[indented]: https://sass-lang.com/documentation/syntax#the-indented-syntax
|
||||
|
||||
## Options
|
||||
|
||||
transpiler
|
||||
: (`string`) The transpiler to use, either `libsass` (default) or `dartsass`. Hugo's extended and extended/deploy editions include the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass) below.
|
||||
|
||||
targetPath
|
||||
: (`string`) If not set, the transformed resource's target path will be the original path of the asset file with its extension replaced by `.css`.
|
||||
|
||||
vars
|
||||
: (`map`) A map of key-value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).
|
||||
|
||||
```scss
|
||||
// LibSass
|
||||
@import "hugo:vars";
|
||||
|
||||
// Dart Sass
|
||||
@use "hugo:vars" as v;
|
||||
```
|
||||
|
||||
outputStyle
|
||||
: (`string`) Output styles available to LibSass include `nested` (default), `expanded`, `compact`, and `compressed`. Output styles available to Dart Sass include `expanded` (default) and `compressed`.
|
||||
|
||||
precision
|
||||
: (`int`) Precision of floating point math. Not applicable to Dart Sass.
|
||||
|
||||
enableSourceMap
|
||||
: (`bool`) If `true`, generates a source map.
|
||||
|
||||
sourceMapIncludeSources
|
||||
: (`bool`) If `true`, embeds sources in the generated source map. Not applicable to LibSass.
|
||||
|
||||
includePaths
|
||||
: (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements.
|
||||
|
||||
```go-html-template
|
||||
{{ $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
|
||||
|
||||
The extended version of Hugo includes [LibSass] to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass].
|
||||
|
||||
Use the latest features of the Sass language by installing Dart Sass in your development and production environments.
|
||||
|
||||
### Installation overview
|
||||
|
||||
Dart Sass is compatible with Hugo v0.114.0 and later.
|
||||
|
||||
If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass.
|
||||
|
||||
If you install Hugo as a [Snap package] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass.
|
||||
|
||||
[^1]: In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass.
|
||||
|
||||
### Installing in a development environment
|
||||
|
||||
When you install Dart Sass somewhere in your PATH, Hugo will find it.
|
||||
|
||||
OS|Package manager|Site|Installation
|
||||
:--|:--|:--|:--
|
||||
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`
|
||||
|
||||
You may also install [prebuilt binaries] for Linux, macOS, and Windows.
|
||||
|
||||
Run `hugo env` to list the active transpilers.
|
||||
|
||||
### Installing in a production environment
|
||||
|
||||
For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
|
||||
|
||||
[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository.
|
||||
|
||||
#### GitHub Pages
|
||||
|
||||
To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:
|
||||
|
||||
```yaml
|
||||
- name: Install Dart Sass
|
||||
run: sudo snap install dart-sass
|
||||
```
|
||||
|
||||
If you are using GitHub Pages for the first time with your repository, GitHub provides a [starter workflow] for Hugo that includes Dart Sass. This is the simplest way to get started.
|
||||
|
||||
#### GitLab Pages
|
||||
|
||||
To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file should look something like this:
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
To install Dart Sass for your builds on Netlify, the `netlify.toml` file should look something like this:
|
||||
|
||||
```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 \
|
||||
"""
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example:
|
||||
|
||||
```go-html-template
|
||||
{{ 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 }}
|
||||
```
|
||||
|
||||
### Miscellaneous
|
||||
|
||||
If you build Hugo from source and run `mage test -v`, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package's strict confinement model.
|
||||
|
||||
[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]: /getting-started/configuration/#configure-build
|
||||
[snap package]: /installation/linux/#snap
|
||||
[snapcraft.io]: https://snapcraft.io/dart-sass
|
||||
[starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml
|
||||
|
||||
Reference in New Issue
Block a user