diff options
Diffstat (limited to 'docs/content/en/hugo-pipes/introduction.md')
| -rwxr-xr-x | docs/content/en/hugo-pipes/introduction.md | 146 |
1 files changed, 21 insertions, 125 deletions
diff --git a/docs/content/en/hugo-pipes/introduction.md b/docs/content/en/hugo-pipes/introduction.md index 2cbb85e32..c993377f8 100755 --- a/docs/content/en/hugo-pipes/introduction.md +++ b/docs/content/en/hugo-pipes/introduction.md @@ -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. - -## 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`. - -With `resources.Get`, the first argument is a local path relative to the `assets` directory/directories: - -```go-html-template -{{ $local := resources.Get "sass/main.scss" }} -``` - -With `resources.GetRemote`, the first argument is a remote URL: - -```go-html-template -{{ $remote := resources.GetRemote "https://www.example.com/styles.scss" }} -``` - -`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 +For `.Page` scoped resources, see the [page resources] section. -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. +[mounted]: /hugo-modules/configuration/#module-configuration-mounts +[page resources]: /content-management/page-resources/ -```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")) }} -``` +## Get a resource -If you need multiple values for the same header key, use a slice: +In order to process an asset with Hugo Pipes, it must be retrieved as a resource. -```go-html-template -{{ $resource := resources.GetRemote "https://example.org/api" (dict "headers" (dict "X-List" (slice "a" "b" "c"))) }} -``` +For global resources, use: -You can also change the request method and set the request body: +- [`resources.ByType`](/functions/resources/bytype/) +- [`resources.Get`](/functions/resources/get/) +- [`resources.GetMatch`](/functions/resources/getmatch/) +- [`resources.Match`](/functions/resources/match/) -```go-html-template -{{ $postResponse := resources.GetRemote "https://example.org/api" (dict - "method" "post" - "body" `{"complete": true}` - "headers" (dict - "Content-Type" "application/json" - ) -)}} -``` +For remote resources, use: -### Caching of remote resources +- [`resources.GetRemote`](/functions/resources/getremote/) -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*. |