Merge branch 'postprocess'

content/en/getting-started/configuration.md

@@ -303,12 +303,16 @@ The `build` configuration section contains global build-realated configuration o
 {{< code-toggle file="config">}}
 [build]
 useResourceCacheWhen="fallback"
+writeStats = false
 {{< /code-toggle >}}
 
 
 useResourceCacheWhen
 : When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available.
 
+writeStats {{< new-in "0.69.0" >}}
+: When enabled, a file named `hugo_stats.json` will be written to your project root with some aggregated data about the build, e.g. list of HTML entities published to be used to do [CSS pruning](/hugo-pipes/postprocess/#css-purging-with-postcss). If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). It's also worth mentioning that, due to the nature of the partial server builds, new HTML entities will be added when you add or change them while the server is running, but the old values will not be removed until you restart the server or run a regular `hugo` build.
+
 ## Configure Server
 
 {{< new-in "0.67.0" >}}

content/en/hugo-pipes/postprocess.md

@@ -0,0 +1,70 @@
+---
+title: PostProcess
+description: Allows delaying of resource transformations to after the build.
+date: 2020-04-09
+categories: [asset management]
+keywords: []
+menu:
+  docs:
+    parent: "pipes"
+    weight: 39
+weight: 39
+sections_weight: 39
+---
+
+Marking a resource with `resources.PostProcess` delays any transformations to after the build, typically because one or more of the steps in the transformation chain depends on the result of the build (e.g. files in `public`).{{< new-in "0.69.0" >}}
+
+A prime use case for this is [CSS purging with PostCSS](#css-purging-with-postcss).
+
+There are currently two limitations to this:
+
+1. This only works for `*.html` files.
+2. You cannot manipulate the values returned from the resource's methods. E.g. the `upper` in this example will not work as expected:
+
+    ```go-html-template
+    {{ $css := resources.Get "css/main.css" }}
+    {{ $css = $css | resources.PostCSS | minify | fingerprint | resources.PostProcess }}
+    {{ $css.RelPermalink | upper }}
+    ```
+
+## CSS purging with PostCSS
+
+{{% note %}}
+There are several ways to set up CSS purging with PostCSS in Hugo. If you have a simple project, you should consider going the simpler route and drop the use of `resources.PostProcess` and just extract keywords from the templates. See the [Tailwind documentation](https://tailwindcss.com/docs/controlling-file-size/#app) for some examples.
+{{% /note %}}
+
+The below configuration will write a `hugo_stats.json` file to the project root as part of the build. If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory).
+
+```toml
+[build]
+  writeStats = true
+```
+
+```js
+const purgecss = require('@fullhuman/postcss-purgecss')({
+    content: [ './hugo_stats.json' ],
+    defaultExtractor: (content) => {
+        let els = JSON.parse(content).htmlElements;
+        return els.tags.concat(els.classes, els.ids);
+    }
+});
+
+module.exports = {
+    plugins: [
+        require('tailwindcss'),
+        require('autoprefixer'),
+        ...(process.env.HUGO_ENVIRONMENT === 'production' ? [ purgecss ] : [])
+    ]
+};
+```
+
+Note that in the example above, the "CSS purge step" will only be applied to the production build. This means that you need to do something like this in your head template to build and include your CSS:
+
+```go-html-template
+{{ $css := resources.Get "css/main.css" }}
+{{ $css = $css | resources.PostCSS }}
+{{ if hugo.IsProduction }}
+{{ $css = $css | minify | fingerprint | resources.PostProcess }}
+{{ end }}
+<link href="{{ $css.RelPermalink }}" rel="stylesheet" />
+```