docs: Guide for Hugo (#918)

* Guide for Hugo * add install links * update postcss.config.js per feedback * Revert "update postcss.config.js per feedback" This reverts commit b06d00e.
FullHuman · Jun 19, 2022 · 17dc7ad · 17dc7ad
1 parent 8c76544
commit 17dc7ad
Show file tree

Hide file tree

Showing 4 changed files with 156 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -50,6 +50,7 @@ You can find the PurgeCSS documentation on [this website](https://purgecss.com).
 - [React.js](https://purgecss.com/guides/react.html)
 - [Next.js](https://purgecss.com/guides/next.html)
 - [Razzle](https://purgecss.com/guides/razzle.html)
+- [Hugo](https://purgecss.com/guides/hugo.html)
 
 ## Getting Started
 

diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts
@@ -178,6 +178,10 @@ export default defineUserConfig<DefaultThemeOptions>({
               text: "WordPress",
               link: "/guides/wordpress",
             },
+            {
+              text: "Hugo",
+              link: "/guides/hugo",
+            },
           ],
         },
         {

diff --git a/docs/README.md b/docs/README.md
@@ -65,6 +65,7 @@ footer: MIT Licensed | Copyright © 2018-present Full Human LTD
 - [Next.js](guides/next.md)
 - [Razzle](guides/razzle.md)
 - [WordPress](guides/wordpress.md)
+- [Hugo](guides/hugo.md)
 
 ### Common Questions
 

diff --git a/docs/guides/hugo.md b/docs/guides/hugo.md
@@ -0,0 +1,150 @@
+---
+title: Hugo
+lang: en-US
+meta:
+  - name: description
+    content: PurgeCSS can be used with Hugo via Hugo Pipes asset processing
+  - itemprop: description
+    content: PurgeCSS can be used with Hugo via Hugo Pipes asset processing
+  - property: og:url
+    content:  https://purgecss.com/guides/hugo
+  - property: og:site_name
+    content: purgecss.com
+  - property: og:type
+    content: website
+  - property: og:image
+    content: https://i.imgur.com/UEiUiJ0.png
+  - property: og:locale
+    content: en_US
+  - property: og:title
+    content: Remove unused CSS - PurgeCSS
+  - property: og:description
+    content: PurgeCSS can be used with Hugo via Hugo Pipes asset processing
+---
+
+# Hugo
+
+> Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.
+
+PurgeCSS can be used with [Hugo](https://gohugo.io/) via Hugo Pipes asset processing.
+
+## Tooling
+
+1. Install [Hugo](https://gohugo.io/getting-started/installing/)
+1. Install [Node.js](https://nodejs.org/en/download/)
+
+## Write Stats
+
+In your `config.toml` file, add this:
+
+```toml
+[build]
+  writeStats = true
+```
+
+Or, If using a `config.yaml` file, add this:
+
+```yaml
+build:
+  writeStats: true
+```
+
+This tells Hugo to write a `hugo_stats.json` file to the project root as part of the build. It includes all tags, classes, and ids from your `*.html` templates.
+
+## Node Packages
+
+Run this to install the necessary packages:
+
+```
+npm install postcss postcss-cli @fullhuman/postcss-purgecss
+```
+
+If the `package.json` file at the project root doesn't exist yet, this will create it.
+
+If it's not already there, add `node_modules/` to your `.gitignore` file.
+
+## PostCSS Config File
+
+Create a `postcss.config.js` file at the project root with these contents:
+
+```js
+const purgecss = require('@fullhuman/postcss-purgecss')({
+  content: ['./hugo_stats.json'],
+  defaultExtractor: content => {
+    const els = JSON.parse(content).htmlElements;
+    return [
+      ...(els.tags || []),
+      ...(els.classes || []),
+      ...(els.ids || []),
+    ];
+  },
+  safelist: []
+});
+
+module.exports = {
+  plugins: [
+    ...(process.env.HUGO_ENVIRONMENT === 'production' ? [purgecss] : [])
+  ]
+};
+```
+
+See the [PurgeCSS configuration docs](https://purgecss.com/configuration.html) for details on each option.
+
+**Note:** `safelist` is an empty array (for now). Remember, only elements from your HTML templates are extracted. So, if your JS adds elements, you'll need to safelist them.
+
+## HTML Template
+
+In the HTML Template for your `<head>`, add this:
+
+```html
+{{ $css := resources.Get "css/style.css" | resources.PostCSS }}
+
+{{ if hugo.IsProduction }}
+  {{ $css = $css | minify | fingerprint | resources.PostProcess }}
+{{ end }}
+
+<link
+  rel="stylesheet"
+  href="{{ $css.RelPermalink }}"
+  integrity="{{ $css.Data.Integrity }}"
+>
+```
+
+This assumes:
+
+- Your CSS file is at `assets/css/style.css`
+- You want to minify and fingerprint the production version of this file
+
+If these assumptions aren't true for you, modify the code accordingly.
+
+## Use it
+
+Cool, now we can use it.
+
+Serve your site in development mode, which is the default:
+
+```
+hugo serve
+```
+
+Open your browser DevTools, go to the Network tab, then note the size of the CSS file.
+
+Now, `Control` + `C` to stop it, then serve your site in production mode:
+
+```
+hugo serve --environment production
+```
+
+Notice the CSS file now has a _much smaller_ size.
+
+## Environment
+
+If you don't want to pass the `--environment production` option, you can set this env var:
+
+```
+HUGO_ENVIRONMENT=production
+```
+
+## References
+
+- <https://gohugo.io/hugo-pipes/postprocess/>