From 23aeb5bd01dc4af6dc6e423f78746a682beb7720 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Wed, 29 Jan 2025 12:15:43 -0800 Subject: [PATCH] Update purgecss example --- content/en/functions/css/PostCSS.md | 19 ++-- content/en/functions/resources/PostProcess.md | 93 +++++++++---------- .../en/getting-started/configuration-build.md | 2 +- 3 files changed, 53 insertions(+), 61 deletions(-) diff --git a/content/en/functions/css/PostCSS.md b/content/en/functions/css/PostCSS.md index 8d4143575..ac911c39a 100644 --- a/content/en/functions/css/PostCSS.md +++ b/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/ diff --git a/content/en/functions/resources/PostProcess.md b/content/en/functions/resources/PostProcess.md index ed144740c..5987749ca 100644 --- a/content/en/functions/resources/PostProcess.md +++ b/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 }} - - {{ else }} - {{ with . | postCSS | minify | fingerprint | resources.PostProcess }} - - {{ 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 diff --git a/content/en/getting-started/configuration-build.md b/content/en/getting-started/configuration-build.md index 654b1f7dc..7ee7a1461 100644 --- a/content/en/getting-started/configuration-build.md +++ b/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.