Optimize generated CSS by removing unused selectors (#2008)

Hugo generates stats about the HTML elements, IDs and classes that can be found in the website,
and we post-process the rendered CSS with postcss-purgecss that uses those stats to remove unused selectors.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

.gitignore

@@ -14,3 +14,4 @@ _rendered.rst
 /spec/
 changelogs/rendered.*
 .hugo_build.lock
+hugo_stats.json

changelogs/internal/newsfragments/2008.clarification

@@ -0,0 +1 @@
+Optimize generated CSS by removing unused selectors.

config/_default/hugo.toml

@@ -1,3 +1,5 @@
+# Default settings.
+
 baseURL = "/"
 title = "Matrix Specification"
 

config/production/hugo.toml

@@ -0,0 +1,6 @@
+# Settings only required when the website is built for production.
+
+# Enable stats to use them to optimize the CSS.
+[build]
+  [build.buildStats]
+    enable = true

layouts/partials/head-css.html

@@ -0,0 +1,38 @@
+{{- /*
+
+    A modified version of the head-css.html partial of Docsy, that adds a call to
+    `resources.PostProcess`, allowing post-processing of the generated CSS to
+    remove unused selectors.
+
+*/ -}}
+
+{{ $scssMain := "scss/main.scss" -}}
+{{ $css := resources.Get $scssMain
+      | toCSS (dict "enableSourceMap" (not hugo.IsProduction)) -}}
+
+{{/* NOTE: we only apply `postCSS` in production or for RTL languages. This
+makes it snappier to develop in Chrome, but it may look sub-optimal in other
+browsers. */ -}}
+
+{{ if eq .Site.Language.LanguageDirection "rtl" -}}
+  {{ $css = $css
+      | postCSS (dict "use" "autoprefixer rtlcss" "noMap" true)
+      | resources.Copy (replace $scssMain "." ".rtl.") -}}
+{{ else if hugo.IsProduction -}}
+  {{ $css = $css | postCSS -}}
+{{ end -}}
+
+{{ if hugo.IsProduction -}}
+  {{ $css = $css | minify | fingerprint | resources.PostProcess -}}
+  <link rel="preload" href="{{ $css.RelPermalink }}" as="style" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
+{{ end -}}
+
+{{ with $css -}}
+  <link href="{{ .RelPermalink }}" rel="stylesheet"
+  {{- with .Data.Integrity }} integrity="{{ . }}" crossorigin="anonymous"{{ end -}}
+  >
+{{ else -}}
+  {{ errorf "Resource not found or error building CSS: %s" $scssMain -}}
+{{ end -}}
+
+{{- /**/ -}}

package.json

@@ -19,9 +19,10 @@
   },
   "homepage": "https://github.com/matrix-org/matrix-spec#readme",
   "devDependencies": {
-    "autoprefixer": "^10.4.2",
+    "@fullhuman/postcss-purgecss": "^6.0.0",
+    "autoprefixer": "^10.4.20",
     "node-fetch": "^2.6.7",
-    "postcss-cli": "^9.1.0",
+    "postcss": "^8.4.49",
-    "postcss": "^8.4.6"
+    "postcss-cli": "^11.0.0"
   }
 }

postcss.config.js

@@ -0,0 +1,15 @@
+// Remove unused CSS selectors.
+const purgecss = require('@fullhuman/postcss-purgecss')({
+    // Use stats generated by Hugo.
+    content: [ './hugo_stats.json' ],
+    defaultExtractor: (content) => {
+        let els = JSON.parse(content).htmlElements;
+        return els.tags.concat(els.classes, els.ids);
+    }
+});
+
+module.exports = {
+     plugins: [
+         ...(process.env.HUGO_ENVIRONMENT === 'production' ? [ purgecss ] : [])
+     ]
+ };