Squashed 'docs/' changes from cfe89ecbc..a4fa0d1d6

a4fa0d1d6 Typos and grammatical changes
513884600 Add hugo pipes documentation

git-subtree-dir: docs
git-subtree-split: a4fa0d1d641b2b3e27a91ae8b1a0a29be3c42ddf

config.toml

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

content/en/hugo-pipes/_index.md

@@ -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
+---

content/en/hugo-pipes/bundling.md

@@ -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" }}
+```

content/en/hugo-pipes/fingerprint.md

@@ -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>
+```

content/en/hugo-pipes/introduction.md

@@ -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 }}">
+```

content/en/hugo-pipes/minification.md

@@ -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 }}
+```

content/en/hugo-pipes/postcss.md

@@ -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) }}
+```

content/en/hugo-pipes/resource-from-string.md

@@ -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>
+```

content/en/hugo-pipes/resource-from-template.md

@@ -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 }}
+```

content/en/hugo-pipes/scss-sass.md

@@ -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 }}
+```