diff --git a/docs/config.toml b/docs/config.toml index 12398be26..6c75f521f 100644 --- a/docs/config.toml +++ b/docs/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 diff --git a/docs/content/en/hugo-pipes/_index.md b/docs/content/en/hugo-pipes/_index.md new file mode 100755 index 000000000..47411072a --- /dev/null +++ b/docs/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 +--- \ No newline at end of file diff --git a/docs/content/en/hugo-pipes/bundling.md b/docs/content/en/hugo-pipes/bundling.md new file mode 100755 index 000000000..32f0a7881 --- /dev/null +++ b/docs/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" }} +``` \ No newline at end of file diff --git a/docs/content/en/hugo-pipes/fingerprint.md b/docs/content/en/hugo-pipes/fingerprint.md new file mode 100755 index 000000000..96aa7f556 --- /dev/null +++ b/docs/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" }} + +``` \ No newline at end of file diff --git a/docs/content/en/hugo-pipes/introduction.md b/docs/content/en/hugo-pipes/introduction.md new file mode 100755 index 000000000..84ac4ec6d --- /dev/null +++ b/docs/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 }} + +``` + +### 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 }} + +``` diff --git a/docs/content/en/hugo-pipes/minification.md b/docs/content/en/hugo-pipes/minification.md new file mode 100755 index 000000000..ce090752f --- /dev/null +++ b/docs/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 }} +``` \ No newline at end of file diff --git a/docs/content/en/hugo-pipes/postcss.md b/docs/content/en/hugo-pipes/postcss.md new file mode 100755 index 000000000..a0ecc6d35 --- /dev/null +++ b/docs/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) }} +``` \ No newline at end of file diff --git a/docs/content/en/hugo-pipes/resource-from-string.md b/docs/content/en/hugo-pipes/resource-from-string.md new file mode 100755 index 000000000..862fcd930 --- /dev/null +++ b/docs/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 }} + + + +``` diff --git a/docs/content/en/hugo-pipes/resource-from-template.md b/docs/content/en/hugo-pipes/resource-from-template.md new file mode 100755 index 000000000..317630b40 --- /dev/null +++ b/docs/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 }} +``` \ No newline at end of file diff --git a/docs/content/en/hugo-pipes/scss-sass.md b/docs/content/en/hugo-pipes/scss-sass.md new file mode 100755 index 000000000..b08d4be08 --- /dev/null +++ b/docs/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 }} +``` \ No newline at end of file