TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-14 15:54:38 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update purgecss example

Browse Source
This commit is contained in:
Joe Mooring 2025-01-29 12:15:43 -08:00 committed by GitHub
parent f7ef83e56c
commit 23aeb5bd01
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 53 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
content/en/functions/css/PostCSS.md
View File

@ -25,9 +25,13 @@ toc: true
Follow the steps below to transform CSS using any of the available [PostCSS plugins]. Follow the steps below to transform CSS using any of the available [PostCSS plugins].
[postcss plugins]: https://postcss.org/docs/postcss-plugins
Step 1 Step 1
: Install [Node.js]. : Install [Node.js].
[node.js]: https://nodejs.org/en/download
Step 2 Step 2
: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules: : 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 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 = { module.exports = {
plugins: [ plugins: [
require('autoprefixer') require('autoprefixer')
] ]
}; };
``` {{< /code >}}
{{% note %}} {{% note %}}
{{% include "functions/resources/_common/postcss-windows-warning.md" %}} {{% 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 ```js
const autoprefixer = require('autoprefixer'); const autoprefixer = require('autoprefixer');
const purgecss = require('@fullhuman/postcss-purgecss');
module.exports = { module.exports = {
plugins: [ plugins: [
autoprefixer, process.env.HUGO_ENVIRONMENT !== 'development' ? autoprefixer : null
process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : 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/

93
content/en/functions/resources/PostProcess.md
View File

@ -13,33 +13,28 @@ action:
toc: true toc: true
--- ---
```go-html-template The `resources.PostProces`s function delays resource transformation steps until the build is complete, primarily for tasks like removing unused CSS rules.
{{ 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 }}
```
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 [autoprefixer]: https://github.com/postcss/autoprefixer
[fingerprint]: /functions/resources/fingerprint/
{{% note %}} [minify]: /functions/resources/minify/
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. [postcss]: /functions/css/postcss/
{{% /note %}} [purgecss]: https://purgecss.com/plugins/postcss.html
Step 1 Step 1
: Install [Node.js]. : Install [Node.js].
[node.js]: https://nodejs.org/en/download
Step 2 Step 2
: Install the required Node.js packages in the root of your project: : 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 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 autoprefixer = require('autoprefixer');
const purgecss = require('@fullhuman/postcss-purgecss')({ const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default;
const purgecss = purgeCSSPlugin({
content: ['./hugo_stats.json'], content: ['./hugo_stats.json'],
defaultExtractor: content => { defaultExtractor: content => {
const els = JSON.parse(content).htmlElements; const els = JSON.parse(content).htmlElements;
@ -68,26 +79,16 @@ const purgecss = require('@fullhuman/postcss-purgecss')({
module.exports = { module.exports = {
plugins: [ plugins: [
process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
autoprefixer, autoprefixer,
process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null
] ]
}; };
``` {{< /code >}}
{{% note %}} {{% note %}}
{{% include "functions/resources/_common/postcss-windows-warning.md" %}} {{% include "functions/resources/_common/postcss-windows-warning.md" %}}
{{% /note %}} {{% /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 Step 5
: Place your CSS file within the `assets/css` directory. : Place your CSS file within the `assets/css` directory.
@ -108,10 +109,10 @@ Step 6
## Environment variables ## 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 ```js
process.env.HUGO_ENVIRONMENT === 'production' ? [autoprefixer] : [] process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
``` ```
PWD PWD
@ -122,16 +123,16 @@ HUGO_ENVIRONMENT
Default is `production` for `hugo` and `development` for `hugo server`. Default is `production` for `hugo` and `development` for `hugo server`.
HUGO_PUBLISHDIR 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_FILE_X
hugo server --renderToDisk : Hugo automatically mounts the following files from your project's root directory under `assets/_jsconfig`:
hugo server --renderStaticToDisk
```
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 ```js
let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.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 = $css | css.PostCSS | minify | fingerprint | resources.PostProcess }}
{{ $css.RelPermalink | strings.ToUpper }} {{ $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

2
content/en/getting-started/configuration-build.md
View File

@ -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. 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. Exclude `class` attributes, `id` attributes, or tags from `hugo_stats.json` with the `disableClasses`, `disableIDs`, and `disableTags` keys.