introduction.md (7030B)
1 ---
2 title: Hugo Pipes Introduction
3 linkTitle: Hugo Pipes
4 description: Hugo Pipes is Hugo's asset processing set of functions.
5 date: 2018-07-14
6 publishdate: 2018-07-14
7 lastmod: 2018-07-14
8 categories: [asset management]
9 keywords: []
10 menu:
11 docs:
12 parent: "pipes"
13 weight: 20
14 weight: 01
15 sections_weight: 01
16 draft: false
17 toc: true
18 aliases: [/assets/]
19 ---
20
21 ## Find Resources in /assets
22
23 This is about the global Resources mounted inside `/assets`. For the `.Page` scoped Resources, see [Page Resources](/content-management/page-resources/).
24
25 Note that you can mount any directory into Hugo's virtual `assets` folder using the [Mount Configuration](/hugo-modules/configuration/#module-config-mounts).
26
27 | Function | Description |
28 | ------------- | ------------- |
29 | `resources.Get` | Get locates the filename given in Hugo's assets filesystem and creates a `Resource` object that can be used for further transformations. See [Get Resource with resources.Get and resources.GetRemote](#get-resource-with-resourcesget-and-resourcesgetremote). |
30 | `resources.GetRemote` | Same as `Get`, but it accepts remote URLs. See [Get Resource with resources.Get and resources.GetRemote](#get-resource-with-resourcesget-and-resourcesgetremote).|
31 | `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. |
32 | `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.|
33
34
35 See the [GoDoc Page](https://pkg.go.dev/github.com/gohugoio/hugo@v0.93.1/tpl/resources) for the `resources` package for an up to date overview of all template functions in this namespace.
36
37
38 ## Get Resource with resources.Get and resources.GetRemote
39
40 In order to process an asset with Hugo Pipes, it must be retrieved as a `Resource` using `resources.Get` or `resources.GetRemote`.
41
42 With `resources.Get`, the first argument is a local path relative to the `assets` directory/directories:
43
44 ```go-html-template
45 {{ $local := resources.Get "sass/main.scss" }}
46 ```
47
48 With `resources.GetRemote`, the first argument is a remote URL:
49
50 ```go-html-template
51 {{ $remote := resources.GetRemote "https://www.example.com/styles.scss" }}
52 ```
53
54 `resources.Get` and `resources.GetRemote` return `nil` if the resource is not found.
55
56 ## Copy a Resource
57
58 {{< new-in "0.100.0" >}}
59
60 `resources.Copy` allows you to copy almost any Hugo `Resource` (the one exception is the `Page`), possibly most useful for renaming things:
61
62 ```go-html-template
63 {{ $resized := $image.Resize "400x400" | resources.Copy "images/mynewname.jpg" }}
64 <img src="{{ $resized.RelPermalink }}">
65 ```
66
67 ### Caching
68
69 By default, Hugo calculates a cache key based on the `URL` and the `options` (e.g. headers) given.
70
71
72 {{< 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.:
73
74
75 ```go-html-template
76 {{ $cacheKey := print $url (now.Format "2006-01-02") }}
77 {{ $resource := resource.GetRemote $url (dict "key" $cacheKey) }}
78 ```
79
80 ### Error Handling
81
82 {{< new-in "0.91.0" >}}
83
84 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.
85
86 ```go-html-template
87 {{ with resources.GetRemote "https://gohugo.io/images/gohugoio-card-1.png" }}
88 {{ with .Err }}
89 {{ warnf "%s" . }}
90 {{ else }}
91 <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
92 {{ end }}
93 {{ end }}
94 ```
95
96 Note that if you do not handle `.Err` yourself, Hugo will fail the build the first time you start using the `Resource` object.
97
98 ### Remote Options
99
100 When fetching a remote `Resource`, `resources.GetRemote` takes an optional options map as the last argument, e.g.:
101
102 ```go-html-template
103 {{ $resource := resources.GetRemote "https://example.org/api" (dict "headers" (dict "Authorization" "Bearer abcd")) }}
104 ```
105
106 If you need multiple values for the same header key, use a slice:
107
108 ```go-html-template
109 {{ $resource := resources.GetRemote "https://example.org/api" (dict "headers" (dict "X-List" (slice "a" "b" "c"))) }}
110 ```
111
112 You can also change the request method and set the request body:
113
114 ```go-html-template
115 {{ $postResponse := resources.GetRemote "https://example.org/api" (dict
116 "method" "post"
117 "body" `{"complete": true}`
118 "headers" (dict
119 "Content-Type" "application/json"
120 )
121 )}}
122 ```
123
124 ### Caching of Remote Resources
125
126 Remote resources fetched with `resources.GetRemote` will be cached on disk. See [Configure File Caches](/getting-started/configuration/#configure-file-caches) for details.
127
128 ## Asset directory
129
130 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.
131
132 ### Asset Publishing
133
134 Hugo publishes assets to the to the `publishDir` (typically `public`) when you invoke `.Permalink`, `.RelPermalink`, or `.Publish`. You can use `.Content` to inline the asset.
135
136 ## Go Pipes
137
138 For improved readability, the Hugo Pipes examples of this documentation will be written using [Go Pipes](/templates/introduction/#pipes):
139
140 ```go-html-template
141 {{ $style := resources.Get "sass/main.scss" | resources.ToCSS | resources.Minify | resources.Fingerprint }}
142 <link rel="stylesheet" href="{{ $style.Permalink }}">
143 ```
144
145 ## Method aliases
146
147 Each Hugo Pipes `resources` transformation method uses a __camelCased__ alias (`toCSS` for `resources.ToCSS`).
148 Non-transformation methods deprived of such aliases are `resources.Get`, `resources.FromString`, `resources.ExecuteAsTemplate` and `resources.Concat`.
149
150 The example above can therefore also be written as follows:
151
152 ```go-html-template
153 {{ $style := resources.Get "sass/main.scss" | toCSS | minify | fingerprint }}
154 <link rel="stylesheet" href="{{ $style.Permalink }}">
155 ```
156
157 ## Caching
158
159 Hugo Pipes invocations are cached based on the entire _pipe chain_.
160
161 An example of a pipe chain is:
162
163 ```go-html-template
164 {{ $mainJs := resources.Get "js/main.js" | js.Build "main.js" | minify | fingerprint }}
165 ```
166
167 The pipe chain is only invoked the first time it is encountered in a site build, and results are otherwise loaded from cache. As such, Hugo Pipes can be used in templates which are executed thousands or millions of times without negatively impacting the build performance.