The PurgeCSS is an awesome tool that remove unused CSS from your site. In this section, we will dive into how the PurgeCSS work, and what should we pay attention to.

How it Works?#

The PurgeCSS requires the following configuration to be set.

  • config. 
1[build]
2  writeStats = true

1build:
2  writeStats: true

1{
2   "build": {
3      "writeStats": true
4   }
5}

It tells Hugo to calculate used tags, classes and ids, and then generates the hugo_stats.json.

1{
2  "htmlElements": {
3    "tags": [],
4    "classes": [],
5    "ids": []
6}

Finally PurgeCSS relies on this file to purge unused CSS.

The PurgeCSS works only under production environment.

We DON NOT recommend overriding the those files.postcss.config.js and assets/main/config/rtl/postcss.config.js, otherwise, unexpected problems will occur during version updates.

Limitations#

The hugo_stats.json only works in *.html templates, that is, any CSS classes, tags and ids used on JavaScript files will still be purged.

But don’t worry, there are two ways to solve this problem.

Extra Stats#

Just create a file called extra_stats.json with the same form of hugo_stats.json on your site root, and put the extra CSS into it manually.

extra_stats.json MUST be commited to your repo.

Put HTML Block into *.html Files#

A common scenario is rendering HTML blocks using JavaScript, if you’re using JavaScript to generate DOM element, any used CSS will be ignored by hugo_stats.json. Of course you can add it to extra_stats.json manually, but there is a better way to do that via template engine.

  1. Firstly, we’ll need to define a template block in *.html partials.
1<script type="text/html" id="template-search-results">
2  <div class="search-results">
3    ...
4  </div>
5</script>

Hugo will calculate used CSS into hugo_stats.json, such as the search-results class.

  1. And then render the template via any template engines.
1const tmplSearchResults = document.getElementById('template-search-results').innerHTML;
2render(tmplSearchResults, data);

Testing#

You’ll need to specify the production environment for local testing via hugo server -e production -b http://localhost:1313, since the PurgeCSS only works on production environment.

Sometimes PurgeCSS and PostProcess don’t work very well, so you may need to restart Hugo Server occasionally.