Squashed 'docs/' changes from cfe89ecbc..a4fa0d1d6

a4fa0d1d6 Typos and grammatical changes
513884600 Add hugo pipes documentation

git-subtree-dir: docs
git-subtree-split: a4fa0d1d641b2b3e27a91ae8b1a0a29be3c42ddf
This commit is contained in:
Bjørn Erik Pedersen 2018-07-19 09:18:11 +02:00
parent b6b37a1f00
commit a3535c8486
10 changed files with 319 additions and 1 deletions

View file

@ -166,7 +166,11 @@ anchor = "smart"
weight = 35 weight = 35
identifier = "variables" identifier = "variables"
url = "/variables/" url = "/variables/"
[[menu.docs]]
name = "Hugo Pipes"
weight = 36
identifier = "pipes"
url = "/hugo-pipes/"
[[menu.docs]] [[menu.docs]]
name = "CLI" name = "CLI"
weight = 40 weight = 40

15
content/en/hugo-pipes/_index.md Executable file
View file

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

View file

@ -0,0 +1,26 @@
---
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
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
weight: 60
weight: 60
sections_weight: 60
draft: false
---
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.
```go-html-template
{{ $plugins := resources.Get "js/plugins.js" }}
{{ $global := resources.Get "js/global.js" }}
{{ $js := slice $plugins $global | resources.Concat "js/bundle.js" }}
```

View file

@ -0,0 +1,29 @@
---
title: Fingerprinting and SRI
description: Hugo Pipes allows Fingerprinting and Subresource Integrity.
date: 2018-07-14
publishdate: 2018-07-14
lastmod: 2018-07-14
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
weight: 70
weight: 70
sections_weight: 70
draft: false
---
Fingerprinting and [SRI](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) can be applied to any asset file using `resources.Fingerpint` which takes two arguments, the resource object and a [hash function](https://en.wikipedia.org/wiki/Cryptographic_hash_function).
The default hash function is `sha256`. Other available functions are `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 function, one hyphen and the base64-encoded hash sum.
```go-html-template
{{ $js := resources.Get "js/global.js" }}
{{ $secureJS := $js | resources.Fingerprint "sha512" }}
<script type="text/javascript" src="{{ $secureJS.Permalink }}" integrity="{{ $secureJS.Data.Integrity }}"></script>
```

View file

@ -0,0 +1,52 @@
---
title: Hugo Pipes Introduction
description: Hugo Pipes is Hugo's asset processing set of functions.
date: 2018-07-14
publishdate: 2018-07-14
lastmod: 2018-07-14
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
weight: 20
weight: 01
sections_weight: 01
draft: false
aliases: [/assets/]
---
### 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.
### From file to resource
In order to process an asset with Hugo Pipes, it must be retrieved as a resource using `resources.Get`, which takes one argument: the filepath of the file relative to the asset directory.
```go-html-template
{{ $style := resources.Get "sass/main.scss" }}
```
### Asset publishing
Assets will only be published (to `/public`) if `.Permalink` or `.RelPermalink` is used.
### Go Pipes
For improved readability, the Hugo Pipes examples of this documentation will be written using [Go Pipes](/templates/introduction/#pipes):
```go-html-template
{{ $style := resources.Get "sass/main.scss" | resources.ToCSS | resources.Minify | resources.Fingerprint }}
<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` and `resources.ExecuteAsTemplate`.
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 }}">
```

View file

@ -0,0 +1,25 @@
---
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
lastmod: 2018-07-14
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
weight: 50
weight: 50
sections_weight: 50
draft: false
---
Any resource of the aforementioned types can be minifed using `resources.Minify` which takes for argument the resource object.
```go-html-template
{{ $css := resources.Get "css/main.css" }}
{{ $style := $css | resources.Minify }}
```

View file

@ -0,0 +1,56 @@
---
title: PostCSS
description: Hugo Pipes can process CSS files with PostCSS.
date: 2018-07-14
publishdate: 2018-07-14
lastmod: 2018-07-14
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
weight: 40
weight: 40
sections_weight: 40
draft: false
---
Any asset file can be processed using `resources.PostCSS` which takes for argument the resource object and a slice of options listed below.
The resource will be processed using the project's or theme's own `postcss.config.js` or any file set with the `config` option.
```go-html-template
{{ $css := resources.Get "css/main.css" }}
{{ $style := $css | resources.PostCSS }}
```
{{% note %}}
Hugo Pipe's PostCSS requires `postcss-cli` javascript package to be installed on the environement along with any PostCSS plugin used.
{{% /note %}}
### Options
config [string]
: Path to the PostCSS configuration file
noMap [bool]
: Default is `true`. Disable the default inline sourcemaps
_If no configuration file is used:_
use [string]
: List of PostCSS plugins to use
parser [string]
: Custom PostCSS parser
stringifier [string]
: Custom PostCSS stringifier
syntax [string]
: Custom postcss syntax
```go-html-template
{{ $style := resources.Get "css/main.css" | resources.PostCSS (dict "config" "customPostCSS.js" "noMap" true) }}
```

View file

@ -0,0 +1,31 @@
---
title: Creating a resource from a string
linkTitle: Resource from String
description: Hugo Pipes allows the creation of a resource from a string.
date: 2018-07-14
publishdate: 2018-07-14
lastmod: 2018-07-14
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
weight: 90
weight: 90
sections_weight: 90
draft: false
---
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.
The following example creates a resource file containing localized variables for every project's languages.
```go-html-template
{{ $string := (printf "var rootURL: '%s'; var apiURL: '%s';" (absURL "/") (.Param "API_URL")) }}
{{ $targetPath := "js/vars.js" }}
{{ $vars := $string | resources.FromString $targetPath }}
{{ $global := resources.Get "js/global.js" | resources.Minify }}
<script type="text/javascript" src="{{ $vars.Permalink }}"></script>
<script type="text/javascript" src="{{ $global.Permalink }}"></script>
```

View file

@ -0,0 +1,38 @@
---
title: Creating a resource from template
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
lastmod: 2018-07-14
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
weight: 80
weight: 80
sections_weight: 80
draft: false
---
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 object, the resource target path and the template context.
```go-html-template
// assets/sass/template.scss
$backgroundColor: {{ .Param "backgroundColor" }};
$textColor: {{ .Param "textColor" }};
body{
background-color:$backgroundColor;
color: $textColor;
}
// [...]
```
```go-html-template
{{ $sassTemplate := resources.Get "sass/template.scss" }}
{{ $style := $sassTemplate | resources.ExecuteAsTemplate "main.scss" . | resources.ToCSS }}
```

View file

@ -0,0 +1,42 @@
---
title: SASS / SCSS
description: Hugo Pipes allows the processing of SASS and SCSS files.
date: 2018-07-14
publishdate: 2018-07-14
lastmod: 2018-07-14
categories: [asset management]
keywords: []
menu:
docs:
parent: "pipes"
weight: 30
weight: 02
sections_weight: 02
draft: false
---
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
{{ $sass := resources.Get "sass/main.scss" }}
{{ $style := $sass | resources.ToCSS }}
```
### Options
targetPath [string]
: If not set, the resource's target path will be the asset file original path with its extension replaced by `.css`.
outputStyle [string]
: Default is `nested`. Other available output styles are `expanded`, `compact` and `compressed`.
precision [int]
: Precision of floating point math.
enableSourceMap [bool]
: When enabled, a source map will be generated.
```go-html-template
{{ $options := (dict "targetPath" "style.css" "outputStyle" "compressed" "enableSourceMap" true) }}
{{ $style := resources.Get "sass/main.scss" | resources.ToCSS $options }}
```