Update purgecss example

content/en/functions/css/PostCSS.md

@@ -25,9 +25,13 @@ toc: true
 
 Follow the steps below to transform CSS using any of the available [PostCSS plugins].
 
+[postcss plugins]: https://postcss.org/docs/postcss-plugins
+
 Step 1
 : Install [Node.js].
 
+[node.js]: https://nodejs.org/en/download
+
 Step 2
 : Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
 
@@ -36,15 +40,15 @@ npm i -D postcss postcss-cli autoprefixer
 ```
 
 Step 3
-: Create a PostCSS configuration file in the root of your project. You must name this file `postcss.config.js` or another [supported file name]. For example:
+: Create a PostCSS configuration file in the root of your project.
 
-```js
+{{< code file=postcss.config.js >}}
 module.exports = {
   plugins: [
     require('autoprefixer')
   ]
 };
-```
+{{< /code >}}
 
 {{% note %}}
 {{% include "functions/resources/_common/postcss-windows-warning.md" %}}
@@ -114,16 +118,9 @@ The current Hugo environment name (set by `--environment` or in configuration or
 
 ```js
 const autoprefixer = require('autoprefixer');
-const purgecss = require('@fullhuman/postcss-purgecss');
 module.exports = {
   plugins: [
-    autoprefixer,
-    process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null
+    process.env.HUGO_ENVIRONMENT !== 'development' ? autoprefixer : null
   ]
 }
 ```
-
-[node.js]: https://nodejs.org/en/download
-[postcss plugins]: https://postcss.org/docs/postcss-plugins
-[supported file name]: https://github.com/postcss/postcss-load-config#usage
-[transpile to CSS]: /functions/css/sass/

content/en/functions/resources/PostProcess.md

@@ -13,33 +13,28 @@ action:
 toc: true
 ---
 
-```go-html-template
-{{ with resources.Get "css/main.css" }}
-  {{ if hugo.IsDevelopment }}
-    <link rel="stylesheet" href="{{ .RelPermalink }}">
-  {{ else }}
-    {{ with . | postCSS | minify | fingerprint | resources.PostProcess }}
-      <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
-    {{ end }}
-  {{ end }}
-{{ end }}
-```
+The `resources.PostProces`s function delays resource transformation steps until the build is complete, primarily for tasks like removing unused CSS rules.
 
-Marking a resource with `resources.PostProcess` postpones transformations until the build has finished.
+## Example
 
-Call `resources.PostProcess` when one or more of the steps in the transformation chain depends on the result of the build.
+In this example, after the build is complete, Hugo will:
 
-A prime use case for this is purging unused CSS rules using the [PurgeCSS] plugin for the PostCSS Node.js package.
+1. Purge unused CSS using the [PurgeCSS] plugin for [PostCSS]
+2. Add vendor prefixes to CSS rules using the [Autoprefixer] plugin for PostCSS
+3. [Minify] the CSS
+4. [Fingerprint] the CSS 
 
-## CSS purging
-
-{{% 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 examples.
-{{% /note %}}
+[autoprefixer]: https://github.com/postcss/autoprefixer
+[fingerprint]: /functions/resources/fingerprint/
+[minify]: /functions/resources/minify/
+[postcss]: /functions/css/postcss/
+[purgecss]: https://purgecss.com/plugins/postcss.html
 
 Step 1
 : Install [Node.js].
 
+[node.js]: https://nodejs.org/en/download
+
 Step 2
 : Install the required Node.js packages in the root of your project:
 
@@ -48,11 +43,27 @@ npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss
 ```
 
 Step 3
-: Create a PostCSS configuration file in the root of your project. You must name this file `postcss.config.js` or another [supported file name]. For example:
+: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`].
 
-```js
+[`config/production`]: /getting-started/configuration/#configuration-directory
+
+{{< code-toggle file=hugo >}}
+[build.buildStats]
+enable = true
+{{< /code-toggle >}}
+
+See the [configure build] documentation for details and options.
+
+[configure build]: /getting-started/configuration/#configure-build
+
+Step 4
+: Create a PostCSS configuration file in the root of your project.
+
+{{< code file="postcss.config.js" copy=true >}}
 const autoprefixer = require('autoprefixer');
-const purgecss = require('@fullhuman/postcss-purgecss')({
+const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default;
+
+const purgecss = purgeCSSPlugin({
   content: ['./hugo_stats.json'],
   defaultExtractor: content => {
     const els = JSON.parse(content).htmlElements;
@@ -68,26 +79,16 @@ const purgecss = require('@fullhuman/postcss-purgecss')({
 
 module.exports = {
   plugins: [
+    process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
     autoprefixer,
-    process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null
   ]
 };
-```
+{{< /code >}}
 
 {{% note %}}
 {{% include "functions/resources/_common/postcss-windows-warning.md" %}}
 {{% /note %}}
 
-Step 4
-: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`].
-
-{{< code-toggle file=hugo >}}
-[build.buildStats]
-enable = true
-{{< /code-toggle >}}
-
-See the [configure build] documentation for details and options.
-
 Step 5
 : Place your CSS file within the `assets/css` directory.
 
@@ -108,10 +109,10 @@ Step 6
 
 ## Environment variables
 
-Hugo passes these environment variables to PostCSS, which allows you to do something like:
+Hugo passes the environment variables below to PostCSS, allowing you to do something like:
 
 ```js
-process.env.HUGO_ENVIRONMENT === 'production' ? [autoprefixer] : []
+process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
 ```
 
 PWD
@@ -122,16 +123,16 @@ HUGO_ENVIRONMENT
 Default is `production` for `hugo` and `development` for `hugo server`.
 
 HUGO_PUBLISHDIR
-: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this directory from PostCSS when running the server, you could run the server with one of these flags:
+: The absolute path to the publish directory, typically `public`. This value points to a directory on disk, even when rendering to memory with the `--renderToMemory` command line flag.
 
-```sh
-hugo server --renderToDisk
-hugo server --renderStaticToDisk
-```
+HUGO_FILE_X
+: Hugo automatically mounts the following files from your project's root directory under `assets/_jsconfig`:
 
-Also, Hugo will add environment variables for all files mounted below `assets/_jsconfig`. A default mount will be set up with files in the project root matching this regexp: `(babel|postcss|tailwind)\.config\.js`.
+- `babel.config.js`
+- `postcss.config.js`
+- `tailwind.config.js`
 
-These will get environment variables named on the form `HUGO_FILE_:filename:` where `:filename:` is all upper case with periods replaced with underscore. This allows you to do something like:
+For each file, Hugo creates a corresponding environment variable named `HUGO_FILE_:filename:`, where `:filename:` is the uppercase version of the filename with periods replaced by underscores.  This allows you to access these files within your JavaScript, for example:
 
 ```js
 let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js';
@@ -150,9 +151,3 @@ You cannot manipulate the values returned from the resource’s methods. For exa
 {{ $css = $css | css.PostCSS | minify | fingerprint | resources.PostProcess }}
 {{ $css.RelPermalink | strings.ToUpper }}
 ```
-
-[node.js]: https://nodejs.org/en/download
-[supported file name]: https://github.com/postcss/postcss-load-config#usage
-[`config/production`]: /getting-started/configuration/#configuration-directory
-[configure build]: /getting-started/configuration/#configure-build
-[purgecss]: https://github.com/FullHuman/purgecss#readme

content/en/getting-started/configuration-build.md

@@ -70,7 +70,7 @@ target
 
 If `enable` is set to `true`, creates a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking.
 
-[removing unused CSS]: /functions/resources/postprocess/#css-purging
+[removing unused CSS]: /functions/resources/postprocess/
 
 Exclude `class` attributes, `id` attributes, or tags from `hugo_stats.json` with the `disableClasses`, `disableIDs`, and `disableTags` keys.