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.toml → 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 -}}
+
+{{- /**/ -}}