mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-22 21:42:50 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-12-04 15:24:01 +01:00
parent 9f978d387f 35dec7c96f
commit d19ed4d4e6
810 changed files with 24147 additions and 7766 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/content/en/hugo-pipes/_index.md
View File

@@ -1,7 +1,7 @@
---
title: Hugo Pipes
linkTitle: Overview
categories: [asset management]
categories: []
keywords: []
menu:
docs:

32
docs/content/en/hugo-pipes/babel.md
View File

@@ -8,14 +8,16 @@ menu:
parent: hugo-pipes
weight: 70
weight: 70
signatures: ["resources.Babel RESOURCE [OPTIONS]", "babel RESOURCE [OPTIONS]"]
function:
aliases: [babel]
returnType: resource.Resource
signatures: ['resources.Babel [OPTIONS] RESOURCE']
---
## Usage
Any JavaScript resource file can be transpiled to another JavaScript version using `resources.Babel` which takes for argument the resource object and an optional dict of options listed below. Babel uses the [babel cli](https://babeljs.io/docs/en/babel-cli).
{{% note %}}
Hugo Pipe's Babel requires the `@babel/cli` and `@babel/core` JavaScript packages to be installed in the project or globally (`npm install -g @babel/cli @babel/core`) along with any Babel plugin(s) or preset(s) used (e.g., `npm install @babel/preset-env --save-dev`).
@@ -26,7 +28,6 @@ If you are using the Hugo Snap package, Babel and plugin(s) need to be installed
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: [
@@ -43,24 +44,23 @@ module.exports = {
### 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).
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
minified
: (`bool`) Save as many bytes as possible when printing
noComments [bool]
: Write comments to generated output (true by default)
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.
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.
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.
### Examples

5
docs/content/en/hugo-pipes/bundling.md
View File

@@ -9,7 +9,10 @@ menu:
parent: hugo-pipes
weight: 90
weight: 90
signatures: ["resources.Concat TARGET_PATH SLICE_RESOURCES"]
action:
aliases: []
returnType: resource.Resource
signatures: ['resources.Concat TARGETPATH [RESOURCE...]']
---
## Usage

5
docs/content/en/hugo-pipes/fingerprint.md
View File

@@ -9,7 +9,10 @@ menu:
parent: hugo-pipes
weight: 100
weight: 100
signatures: ["resources.Fingerprint RESOURCE [ALGORITHM]", "fingerprint RESOURCE [ALGORITHM]"]
action:
aliases: [fingerprint]
returnType: resource.Resource
signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE']
---
## Usage

146
docs/content/en/hugo-pipes/introduction.md
View File

@@ -13,139 +13,47 @@ toc: true
aliases: [/assets/]
---
## Find resources in /assets
## Find resources in assets
This is about the global Resources mounted inside `/assets`. For the `.Page` scoped Resources, see [Page Resources](/content-management/page-resources/).
This is about global and remote resources.
Note that you can mount any directory into Hugo's virtual `assets` folder using the [Mount Configuration](/hugo-modules/configuration/#module-configuration-mounts).
global resource
: A file within the assets directory, or within any directory [mounted] to the assets directory.
| Function | Description |
| ------------- | ------------- |
| `resources.Get` | Get locates the file name given in Hugo's assets filesystem and creates a `Resource` object that can be used for further transformations. See [Get a resource](#get-a-resource). |
| `resources.GetRemote` | Same as `Get`, but it accepts remote URLs. See [Get a resource](#get-a-resource).|
| `resources.GetMatch` | `GetMatch` finds the first Resource matching the given pattern, or nil if none found. See Match for a more complete explanation about the rules used. |
| `resources.Match` | `Match` gets all resources matching the given base path prefix, e.g "*.png" will match all png files. The "*" does not match path delimiters (/), so if you organize your resources in sub-folders, you need to be explicit about it, e.g.: "images/*.png". To match any PNG image anywhere in the bundle you can do "\*\*.png", and to match all PNG images below the images folder, use "images/\*\*.jpg". The matching is case insensitive. Match matches by using the files name with path relative to the file system root with Unix style slashes (/) and no leading slash, e.g. "images/logo.png". See https://github.com/gobwas/glob for the full rules set.|
remote resource
: A file on a remote server, accessible via HTTP or HTTPS.
See the [GoDoc Page](https://pkg.go.dev/github.com/gohugoio/hugo/tpl/resources) for the `resources` package for an up to date overview of all template functions in this namespace.
For `.Page` scoped resources, see the [page resources] section.
[mounted]: /hugo-modules/configuration/#module-configuration-mounts
[page resources]: /content-management/page-resources/
## Get a resource
In order to process an asset with Hugo Pipes, it must be retrieved as a `Resource` using `resources.Get` or `resources.GetRemote`.
In order to process an asset with Hugo Pipes, it must be retrieved as a resource.
With `resources.Get`, the first argument is a local path relative to the `assets` directory/directories:
For global resources, use:
```go-html-template
{{ $local := resources.Get "sass/main.scss" }}
```
- [`resources.ByType`](/functions/resources/bytype/)
- [`resources.Get`](/functions/resources/get/)
- [`resources.GetMatch`](/functions/resources/getmatch/)
- [`resources.Match`](/functions/resources/match/)
With `resources.GetRemote`, the first argument is a remote URL:
For remote resources, use:
```go-html-template
{{ $remote := resources.GetRemote "https://www.example.com/styles.scss" }}
```
- [`resources.GetRemote`](/functions/resources/getremote/)
`resources.Get` and `resources.GetRemote` return `nil` if the resource is not found.
{{< new-in "0.110.0" >}} You can get information about the HTTP Response using `.Data` in the returned `Resource`. This is especially useful for HEAD request without any body. The Data object contains:
StatusCode
: The HTTP status code, e.g. 200
Status
: The HTTP status text, e.g. "200 OK"
TransferEncoding
: The transfer encoding, e.g. "chunked"
ContentLength
: The content length, e.g. 1234
ContentType
: The content type, e.g. "text/html"
### Caching
By default, Hugo calculates a cache key based on the `URL` and the `options` (e.g. headers) given.
{{< new-in "0.97.0" >}} You can override this by setting a `key` in the options map. This can be used to get more fine grained control over how often a remote resource is fetched, e.g.:
```go-html-template
{{ $cacheKey := print $url (now.Format "2006-01-02") }}
{{ $resource := resource.GetRemote $url (dict "key" $cacheKey) }}
```
### Error handling
The return value from `resources.GetRemote` includes an `.Err` method that will return an error if the call failed. If you want to just log any error as a `WARNING` you can use a construct similar to the one below.
```go-html-template
{{ with resources.GetRemote "https://gohugo.io/images/gohugoio-card-1.png" }}
{{ with .Err }}
{{ warnf "%s" . }}
{{ else }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```
Note that if you do not handle `.Err` yourself, Hugo will fail the build the first time you start using the `Resource` object.
### Remote options
When fetching a remote `Resource`, `resources.GetRemote` takes an optional options map as the second argument, e.g.:
```go-html-template
{{ $resource := resources.GetRemote "https://example.org/api" (dict "headers" (dict "Authorization" "Bearer abcd")) }}
```
If you need multiple values for the same header key, use a slice:
```go-html-template
{{ $resource := resources.GetRemote "https://example.org/api" (dict "headers" (dict "X-List" (slice "a" "b" "c"))) }}
```
You can also change the request method and set the request body:
```go-html-template
{{ $postResponse := resources.GetRemote "https://example.org/api" (dict
"method" "post"
"body" `{"complete": true}`
"headers" (dict
"Content-Type" "application/json"
)
)}}
```
### Caching of remote resources
Remote resources fetched with `resources.GetRemote` will be cached on disk. See [Configure File Caches](/getting-started/configuration/#configure-file-caches) for details.
See the [GoDoc Page](https://pkg.go.dev/github.com/gohugoio/hugo/tpl/resources) for the `resources` package for an up to date overview of all template functions in this namespace.
## Copy a resource
{{< new-in "0.100.0" >}}
Use `resources.Copy` to copy a page resource or a global resource. Commonly used to change a resource's published path, `resources.Copy` takes two arguments: the target path relative to the root of the `publishDir` (with or without a leading `/`), and the resource to copy.
```go-html-template
{{ with resources.Get "img/a.jpg" }}
{{ with .Resize "300x" }}
{{ with resources.Copy "img/a-new.jpg" . }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
{{ end }}
```
{{% note %}}
The target path must be different than the source path, as shown in the example above. See GitHub issue [#10412](https://github.com/gohugoio/hugo/issues/10412).
{{% /note %}}
See the [`resources.Copy`](/functions/resources/copy/) function.
## Asset directory
Asset files must be stored in the asset directory. This is `/assets` by default, but can be configured via the configuration file's `assetDir` key.
### Asset publishing
## Asset publishing
Hugo publishes assets to the `publishDir` (typically `public`) when you invoke `.Permalink`, `.RelPermalink`, or `.Publish`. You can use `.Content` to inline the asset.
@@ -158,18 +66,6 @@ For improved readability, the Hugo Pipes examples of this documentation will be
<link rel="stylesheet" href="{{ $style.Permalink }}">
```
## Method aliases
Each Hugo Pipes `resources` transformation method uses a __camelCased__ alias (`toCSS` for `resources.ToCSS`).
Non-transformation methods deprived of such aliases are `resources.Get`, `resources.FromString`, `resources.ExecuteAsTemplate` and `resources.Concat`.
The example above can therefore also be written as follows:
```go-html-template
{{ $style := resources.Get "sass/main.scss" | toCSS | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}">
```
## Caching
Hugo Pipes invocations are cached based on the entire *pipe chain*.

60
docs/content/en/hugo-pipes/js.md
View File

@@ -1,7 +1,7 @@
---
title: js.Build
linkTitle: JavaScript building
description: Process a JavaScript file with [ESBuild](https://github.com/evanw/esbuild).
description: Bundle, transpile, tree shake, and minify JavaScript resources.
categories: [asset management]
keywords: []
menu:
@@ -9,7 +9,10 @@ menu:
parent: hugo-pipes
weight: 60
weight: 60
signatures: ["js.Build RESOURCE [OPTIONS]"]
action:
aliases: []
returnType: resource.Resource
signatures: ['js.Build [OPTIONS] RESOURCE']
---
## Usage
@@ -18,12 +21,12 @@ Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build
### Options
targetPath [string]
: If not set, the source path will be used as the base target path.
targetPath
: (`string`) If not set, the source path will be used as the base target path.
Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript.
params [map or slice]
: Params that can be imported as JSON in your JS files, e.g.:
params
: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.:
```go-html-template
{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
@@ -36,14 +39,14 @@ import * as params from '@params';
Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into `/assets` and import them directly.
minify [bool]
: Let `js.Build` handle the minification.
minify
: (`bool`) Let `js.Build` handle the minification.
inject [slice]
: This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject
inject
: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject
shims [map]
: This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
shims
: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
```go-html-template
{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }}
@@ -69,29 +72,28 @@ import * as React from 'react'
import * as ReactDOM from 'react-dom';
```
target [string]
: The language target.
target
: (`string`) The language target.
One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`.
Default is `esnext`.
externals [slice]
: External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external
externals
: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external
defines [map]
: Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value.
defines
: (`map`) Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value.
```go-html-template
{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
```
format [string]
: The output format.
format
: (`string`) The output format.
One of: `iife`, `cjs`, `esm`.
Default is `iife`, a self-executing function, suitable for inclusion as a <script> tag.
Default is `iife`, a self-executing function, suitable for inclusion as a `<script>` tag.
sourceMap [string]
: Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created.
sourceMap
: (`string`) Whether to generate `inline` or `external` source maps from esbuild. External source maps will be written to the target with the output file name + ".map". Input source maps can be read from js.Build and node modules and combined into the output source maps. By default, source maps are not created.
### Import JS code from /assets
@@ -121,7 +123,7 @@ For other files (e.g. `JSON`, `CSS`) you need to use the relative path including
import * as data from 'my/module/data.json';
```
Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
Also note the new `params` option that can be passed from template to your JS files, e.g.:
@@ -136,15 +138,15 @@ import * as params from '@params';
Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/getting-started/configuration/#configure-build).
### Include dependencies In package.json / node_modules
Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
The start directory for resolving npm packages (aka. packages that live inside a `node_modules` folder) is always the main project folder.
**Note:** If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project.
{{% note %}}
If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project.
{{% /note %}}
### Examples

5
docs/content/en/hugo-pipes/minification.md
View File

@@ -9,7 +9,10 @@ menu:
parent: hugo-pipes
weight: 80
weight: 80
signatures: ["resources.Minify RESOURCE", "minify RESOURCE"]
action:
aliases: [minify]
returnType: resource.Resource
signatures: [resources.Minify RESOURCE]
---
## Usage

25
docs/content/en/hugo-pipes/postcss.md
View File

@@ -7,9 +7,12 @@ menu:
docs:
parent: hugo-pipes
weight: 40
toc: true
weight: 40
signatures: ["resources.PostCSS RESOURCE [OPTIONS]", "postCSS RESOURCE [OPTIONS]"]
toc: true
action:
aliases: [postCSS]
returnType: resource.Resource
signatures: ['resources.PostCSS [OPTIONS] RESOURCE']
---
## Setup
@@ -22,8 +25,8 @@ Step 1
Step 2
: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to CSS rules:
```bash
npm install postcss postcss-cli autoprefixer
```sh
npm i -D postcss postcss-cli autoprefixer
```
Step 3
@@ -31,7 +34,7 @@ Step 3
[supported file names]: https://github.com/postcss/postcss-load-config#usage
{{< code file="postcss.config.js" >}}
{{< code file=postcss.config.js >}}
module.exports = {
plugins: [
require('autoprefixer')
@@ -49,7 +52,7 @@ Step 4
Step 5
: Capture the CSS file as a resource and pipe it through `resources.PostCSS` (alias `postCSS`):
{{< code file="layouts/partials/css.html" >}}
{{< code file=layouts/partials/css.html >}}
{{ with resources.Get "css/main.css" | postCSS }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
@@ -57,7 +60,7 @@ Step 5
If starting with a Sass file within the `assets` directory:
{{< code file="layouts/partials/css.html" >}}
{{< code file=layouts/partials/css.html >}}
{{ with resources.Get "sass/main.scss" | toCSS | postCSS }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
@@ -79,10 +82,10 @@ URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+San
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 {{< new-in "0.99.0" >}}
skipInlineImportsNotFound {{< new-in 0.99.0 >}}
: (`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.
{{< code file="layouts/partials/css.html" >}}
{{< code file=layouts/partials/css.html >}}
{{ $opts := dict "config" "config-directory" "noMap" true }}
{{ with resources.Get "css/main.css" | postCSS $opts }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
@@ -105,7 +108,7 @@ stringifier
syntax
: (`string`) Custom postcss syntax.
{{< code file="layouts/partials/css.html" >}}
{{< code file=layouts/partials/css.html >}}
{{ $opts := dict "use" "autoprefixer postcss-color-alpha" }}
{{ with resources.Get "css/main.css" | postCSS $opts }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
@@ -116,7 +119,7 @@ syntax
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:
{{< code file="postcss.config.js" >}}
{{< code file=postcss.config.js >}}
module.exports = {
plugins: [
require('autoprefixer'),

12
docs/content/en/hugo-pipes/postprocess.md
View File

@@ -8,7 +8,10 @@ menu:
parent: hugo-pipes
weight: 50
weight: 50
signatures: ["resources.PostProcess RESOURCE"]
action:
aliases: []
returnType: postpub.PostPublishedResource
signatures: [resources.PostProcess RESOURCE]
---
## Usage
@@ -36,7 +39,7 @@ There are several ways to set up CSS purging with PostCSS in Hugo. If you have a
The below configuration will write a `hugo_stats.json` file to the project root as part of the build. If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory).
{{< code-toggle file="hugo" >}}
{{< code-toggle file=hugo >}}
[build.buildStats]
enable = true
{{< /code-toggle >}}
@@ -74,7 +77,6 @@ Note that in the example above, the "CSS purge step" will only be applied to the
<link href="{{ $css.RelPermalink }}" rel="stylesheet" />
```
## Hugo environment variables available in PostCSS
These are the environment variables Hugo passes down to PostCSS (and Babel), which allows you do do `process.env.HUGO_ENVIRONMENT === 'production' ? [autoprefixer] : []` and similar:
@@ -86,9 +88,9 @@ HUGO_ENVIRONMENT
: The value e.g. set with `hugo -e production` (defaults to `production` for `hugo` and `development` for `hugo server`).
HUGO_PUBLISHDIR
: {{< new-in "0.109.0" >}} 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 folder from PostCSS when running the server, you could run the server with one of these flags:
: {{< new-in 0.109.0 >}} 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 folder from PostCSS when running the server, you could run the server with one of these flags:
```text
```sh
hugo server --renderToDisk
hugo server --renderStaticToDisk
```

5
docs/content/en/hugo-pipes/resource-from-string.md
View File

@@ -9,7 +9,10 @@ menu:
parent: hugo-pipes
weight: 110
weight: 110
signatures: ["resources.FromString TARGET_PATH CONTENT"]
action:
aliases: []
returnType: resource.Resource
signatures: [resources.FromString TARGETPATH STRING]
---
## Usage

5
docs/content/en/hugo-pipes/resource-from-template.md
View File

@@ -9,7 +9,10 @@ menu:
parent: hugo-pipes
weight: 120
weight: 120
signatures: ["resources.ExecuteAsTemplate TARGET_PATH CONTEXT RESOURCE"]
action:
aliases: []
returnType: resource.Resource
signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE]
---
## Usage

23
docs/content/en/hugo-pipes/transpile-sass-to-css.md
View File

@@ -7,9 +7,13 @@ keywords: []
menu:
docs:
parent: hugo-pipes
returnType: resource.Resource
weight: 30
weight: 30
signatures: ["resources.ToCSS RESOURCE [OPTIONS]", "toCSS RESOURCE [OPTIONS]"]
action:
aliases: [toCSS]
returnType: resource.Resource
signatures: ['resources.ToCSS [OPTIONS] RESOURCE']
toc: true
aliases: [/hugo-pipes/transform-to-css/]
---
@@ -19,8 +23,8 @@ aliases: [/hugo-pipes/transform-to-css/]
Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended edition, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language.
```go-html-template
{{ $options := dict "transpiler" "libsass" "targetPath" "css/style.css" }}
{{ with resources.Get "sass/main.scss" | toCSS $options | minify | fingerprint }}
{{ $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 }}
```
@@ -30,7 +34,6 @@ 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
@@ -39,7 +42,7 @@ transpiler
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 {{< new-in "0.109.0" >}}
vars {{< new-in 0.109.0 >}}
: (`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
@@ -59,21 +62,21 @@ precision
enableSourceMap
: (`bool`) If `true`, generates a source map.
sourceMapIncludeSources {{< new-in "0.108.0" >}}
sourceMapIncludeSources {{< new-in 0.108.0 >}}
: (`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
{{ $options := dict
{{ $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 $options | minify | fingerprint }}
{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}
```
@@ -187,8 +190,8 @@ command = """\
To transpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example:
```go-html-template
{{ $options := dict "transpiler" "dartsass" "targetPath" "css/style.css" }}
{{ with resources.Get "sass/main.scss" | toCSS $options | minify | fingerprint }}
{{ $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 }}
```