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

Merge commit 'f96384a3b596f9bc0a3a035970b09b2c601f0ccb'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-05-22 16:47:07 +02:00
parent 4cac5f5e30 f96384a3b5
commit b95e156940
341 changed files with 3107 additions and 4238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,13 +1,10 @@
---
title: Hugo Pipes Overview
date: 2018-07-14
publishdate: 2018-07-14
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 10
weight: 10
sections_weight: 10
---
---

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

@@ -1,18 +1,18 @@
---
title: Babel
description: Hugo Pipes can process JS files with Babel.
date: 2019-03-21
publishdate: 2019-03-21
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 48
weight: 48
sections_weight: 48
signature: ["resources.Babel RESOURCE [OPTIONS]", "babel RESOURCE [OPTIONS]"]
---
## 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).

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

@@ -1,20 +1,20 @@
---
title: Asset bundling
description: Hugo Pipes can bundle any number of assets together.
date: 2018-07-14
publishdate: 2018-07-14
lastmod: 2018-07-14
title: Concat
linkTitle: Concatenating assets
description: Bundle any number of assets into one resource.
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 60
weight: 60
sections_weight: 60
signature: ["resources.Concat TARGET_PATH SLICE_RESOURCES"]
---
Asset files of the same MIME type can be bundled into one resource using `resources.Concat` which takes two arguments, a target path and a slice of resource objects.
## Usage
Asset files of the same MIME type can be bundled into one resource using `resources.Concat` which takes two arguments, the target path for the created resource bundle and a slice of resource objects to be concatenated.
```go-html-template
{{ $plugins := resources.Get "js/plugins.js" }}

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

@@ -1,23 +1,24 @@
---
title: Fingerprinting and SRI
description: Hugo Pipes allows Fingerprinting and Subresource Integrity.
date: 2018-07-14
publishdate: 2018-07-14
title: Fingerprint
linkTitle: Fingerprinting and SRI
description: Process a given resource, adding a hash string of the resource's content.
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 70
weight: 70
sections_weight: 70
signature: ["resources.Fingerprint RESOURCE [ALGORITHM]", "fingerprint RESOURCE [ALGORITHM]"]
---
Fingerprinting and [SRI](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) can be applied to any asset file using `resources.Fingerprint` which takes two arguments, the resource object and a [hash function](https://en.wikipedia.org/wiki/Cryptographic_hash_function).
## Usage
The default hash function is `sha256`. Other available functions are `sha384` (from Hugo `0.55`), `sha512` and `md5`.
Fingerprinting and [SRI](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) can be applied to any asset file using `resources.Fingerprint` which takes two arguments, the resource object and an optional [hash algorithm](https://en.wikipedia.org/wiki/Secure_Hash_Algorithms).
Any so processed asset will bear a `.Data.Integrity` property containing an integrity string, which is made up of the name of the hash function, one hyphen and the base64-encoded hash sum.
The default hash algorithm is `sha256`. Other available algorithms are `sha384` and (as of Hugo `0.55`) `sha512` and `md5`.
Any so processed asset will bear a `.Data.Integrity` property containing an integrity string, which is made up of the name of the hash algorithm, one hyphen and the base64-encoded hash sum.
```go-html-template
{{ $js := resources.Get "js/global.js" }}

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

@@ -2,17 +2,13 @@
title: Hugo Pipes Introduction
linkTitle: Hugo Pipes
description: Hugo Pipes is Hugo's asset processing set of functions.
date: 2018-07-14
publishdate: 2018-07-14
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 20
weight: 01
sections_weight: 01
draft: false
toc: true
aliases: [/assets/]
---
@@ -63,18 +59,6 @@ ContentLength
ContentType
: The content type, e.g. "text/html"
## Copy a Resource
{{< new-in "0.100.0" >}}
`resources.Copy` allows you to copy almost any Hugo `Resource` (the one exception is the `Page`), possibly most useful for renaming things:
```go-html-template
{{ $resized := $image.Resize "400x400" | resources.Copy "images/mynewname.jpg" }}
<img src="{{ $resized.RelPermalink }}">
```
### Caching
By default, Hugo calculates a cache key based on the `URL` and the `options` (e.g. headers) given.
@@ -105,16 +89,16 @@ Note that if you do not handle `.Err` yourself, Hugo will fail the build the fir
### Remote Options
When fetching a remote `Resource`, `resources.GetRemote` takes an optional options map as the last argument, e.g.:
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")) }}
{{ $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"))) }}
{{ $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:
@@ -133,7 +117,6 @@ You can also change the request method and set the request body:
Remote resources fetched with `resources.GetRemote` will be cached on disk. See [Configure File Caches](/getting-started/configuration/#configure-file-caches) for details.
## Copy a Resource
{{< new-in "0.100.0" >}}

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

@@ -1,18 +1,19 @@
---
title: JavaScript Building
description: Hugo Pipes can process JavaScript files with [ESBuild](https://github.com/evanw/esbuild).
date: 2020-07-20
publishdate: 2020-07-20
title: js.Build
linkTitle: JavaScript Building
description: Process a JavaScript file with [ESBuild](https://github.com/evanw/esbuild).
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 45
weight: 45
sections_weight: 45
signature: ["js.Build RESOURCE [OPTIONS]"]
---
## Usage
Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build` which takes for argument either a string for the filepath or a dict of options listed below.
### Options

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

@@ -1,19 +1,20 @@
---
title: Asset minification
description: Hugo Pipes allows the minification of any CSS, JS, JSON, HTML, SVG or XML resource.
date: 2018-07-14
publishdate: 2018-07-14
title: Minify
linkTitle: Asset minification
description: Minifies a given resource.
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 50
weight: 50
sections_weight: 50
signature: ["resources.Minify RESOURCE", "minify RESOURCE"]
---
Any resource of the aforementioned types can be minified using `resources.Minify` which takes for argument the resource object.
## Usage
Any CSS, JS, JSON, HTML, SVG or XML resource can be minified using `resources.Minify` which takes for argument the resource object.
```go-html-template
{{ $css := resources.Get "css/main.css" }}

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

@@ -1,74 +1,122 @@
---
title: PostCSS
description: Hugo Pipes can process CSS files with PostCSS.
description: Process CSS files with PostCSS, using any of the available plugins.
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 40
toc: true
weight: 40
signature: ["resources.PostCSS RESOURCE [OPTIONS]", "postCSS RESOURCE [OPTIONS]"]
---
Any asset file can be processed using `resources.PostCSS` which takes for argument the resource object and a slice of options listed below.
## Setup
The resource will be processed using the project's or theme's own `postcss.config.js` or any file set with the `config` option.
Follow the steps below to transform CSS using any of the [available PostCSS plugins](https://www.postcss.parts/).
```go-html-template
{{ $css := resources.Get "css/main.css" }}
{{ $style := $css | resources.PostCSS }}
```
Step 1
: Install [Node.js](https://nodejs.org/en/download).
You must install the required Node.js packages to use the PostCSS feature. For example, to use the `autoprefixer` package, run these commands from the root of your project:
Step 2
: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to CSS rules:
```text
```bash
npm install postcss postcss-cli autoprefixer
```
### Options
Step 3
: Create a PostCSS configuration file in the root of your project. You must name this file `postcss.config.js` or one of the other [supported file names]. For example:
config [string]
: Set a custom directory to look for a config file
[supported file names]: https://github.com/postcss/postcss-load-config#usage
noMap [bool]
: Default is `false`. Disable the default inline sourcemaps
{{< code file="postcss.config.js" >}}
module.exports = {
plugins: [
require('autoprefixer')
]
};
{{< /code >}}
inlineImports [bool]
: Default is `false`. Enable inlining of @import statements. It does so recursively, but will only import a file once.
{{% note %}}
If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example](https://github.com/postcss/postcss-load-config#packagejson) and issue [#7333](https://github.com/gohugoio/hugo/issues/7333).
{{% /note %}}
Step 4
: Place your CSS file within the `assets` directory.
Step 5
: Capture the CSS file as a resource and pipe it through `resources.PostCSS` (alias `postCSS`):
{{< code file="layouts/partials/css.html" >}}
{{ with resources.Get "css/main.css" | postCSS }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
{{< /code >}}
If starting with a Sass file within the `assets` directory:
{{< code file="layouts/partials/css.html" >}}
{{ with resources.Get "sass/main.scss" | toCSS | postCSS }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
{{< /code >}}
## 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] {{< new-in "0.99.0" >}}
: 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.
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.
_If no configuration file is used:_
{{< 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 }}">
{{ end }}
{{< /code >}}
use [string]
: Space-delimited list of PostCSS plugins to use
## No configuration file
parser [string]
: Custom PostCSS parser
To avoid using a PostCSS configuration file, you can specify a minimal configuration using the options map.
stringifier [string]
: Custom PostCSS stringifier
use
: (`string`) A space-delimited list of PostCSS plugins to use.
syntax [string]
: Custom postcss syntax
parser
: (`string`) A custom PostCSS parser.
```go-html-template
{{ $options := dict "config" "/path/to/custom-config-directory" "noMap" true }}
{{ $style := resources.Get "css/main.css" | resources.PostCSS $options }}
stringifier
: (`string`) A custom PostCSS stringifier.
{{ $options := dict "use" "autoprefixer postcss-color-alpha" }}
{{ $style := resources.Get "css/main.css" | resources.PostCSS $options }}
```
syntax
: (`string`) Custom postcss syntax.
## Check Hugo Environment from postcss.config.js
{{< 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 }}">
{{ end }}
{{< /code >}}
## Check Hugo environment
The current Hugo environment name (set by `--environment` or in config or OS environment) is available in the Node context, which allows constructs like this:
```js
{{< code file="postcss.config.js" >}}
module.exports = {
plugins: [
require('autoprefixer'),
@@ -77,4 +125,4 @@ module.exports = {
: []
]
}
```
{{< /code >}}

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

@@ -1,17 +1,18 @@
---
title: PostProcess
description: Allows delaying of resource transformations to after the build.
date: 2020-04-09
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 39
weight: 39
sections_weight: 39
signature: ["resources.PostProcess RESOURCE"]
---
## Usage
Marking a resource with `resources.PostProcess` delays any transformations to after the build, typically because one or more of the steps in the transformation chain depends on the result of the build (e.g. files in `public`).
A prime use case for this is [CSS purging with PostCSS](#css-purging-with-postcss).
@@ -80,7 +81,7 @@ HUGO_ENVIRONMENT (and the alias HUGO_ENV)
: 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:
```
hugo server --renderToDisk
@@ -89,9 +90,8 @@ hugo server --renderStaticToDisk
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`.
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 do do this and similar:
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 this and similar:
```js
let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js';
```

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

@@ -1,20 +1,20 @@
---
title: Creating a resource from a string
title: FromString
linkTitle: Resource from String
description: Hugo Pipes allows the creation of a resource from a string.
date: 2018-07-14
publishdate: 2018-07-14
description: Creates a resource from a string.
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 90
weight: 90
sections_weight: 90
signature: ["resources.FromString TARGET_PATH CONTENT"]
---
It is possible to create a resource directly from the template using `resources.FromString` which takes two arguments, the given string and the resource target path.
## Usage
It is possible to create a resource directly from the template using `resources.FromString` which takes two arguments, the target path for the created resource and the given content string.
The following example creates a resource file containing localized variables for every project's languages.

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

@@ -1,22 +1,22 @@
---
title: Creating a resource from template
title: ExecuteAsTemplate
linkTitle: Resource from Template
description: Hugo Pipes allows the creation of a resource from an asset file using Go Template.
date: 2018-07-14
publishdate: 2018-07-14
description: Creates a resource from a template
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 80
weight: 80
sections_weight: 80
signature: ["resources.ExecuteAsTemplate TARGET_PATH CONTEXT RESOURCE"]
---
## Usage
In order to use Hugo Pipes function on an asset file containing Go Template magic the function `resources.ExecuteAsTemplate` must be used.
The function takes three arguments: the resource target path, the template context, and the resource object.
The function takes three arguments: the target path for the created resource, the template context, and the resource object.
```go-html-template
// assets/sass/template.scss

17
docs/content/en/hugo-pipes/scss-sass.md → docs/content/en/hugo-pipes/transform-to-css.md Executable file → Normal file
View File

@@ -1,18 +1,19 @@
---
title: Sass / SCSS
description: Hugo Pipes allows the processing of Sass and SCSS files.
date: 2018-07-14
publishdate: 2018-07-14
title: ToCSS
linkTitle: Transpile Sass to SCSS
description: Transpile Sass to CSS.
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
parent: pipes
weight: 30
weight: 02
sections_weight: 02
signature: ["resources.ToCSS RESOURCE [OPTIONS]", "toCSS RESOURCE [OPTIONS]"]
---
## Usage
Any Sass or SCSS file can be transformed into a CSS file using `resources.ToCSS` which takes two arguments, the resource object and a map of options listed below.
```go-html-template
@@ -27,7 +28,7 @@ transpiler [string]
: The `transpiler` to use, valid values are `libsass` (default) and `dartsass`. If you want to use Hugo with Dart Sass you need to download a release binary from [Embedded Dart Sass](https://github.com/sass/dart-sass-embedded/releases) and make sure it's in your PC's `$PATH` (or `%PATH%` on Windows).
targetPath [string]
: If not set, the resource's target path will be the asset file original path with its extension replaced by `.css`.
: If not set, the transformed resource's target path will be the asset file original path with its extension replaced by `.css`.
vars [map]
: Map of key/value pairs that will be available in the `hugo:vars` namespace, e.g. with `@use "hugo:vars" as v;` or (globally) with `@import "hugo:vars";` {{< new-in "0.109.0" >}}
@@ -53,5 +54,5 @@ includePaths [string slice]
```
{{% note %}}
Setting `outputStyle` to `compressed` will handle Sass/SCSS files minification better than the more generic [`resources.Minify`]({{< ref "minification">}}).
Setting `outputStyle` to `compressed` will handle Sass/SCSS files minification better than the more generic [`resources.Minify`](/hugo-pipes/minification).
{{% /note %}}