aboutsummaryrefslogtreecommitdiffhomepage
path: root/content/en/functions/resources/PostCSS.md
blob: f495b16fe19d51b0f9f72003cd6e5dad7aff67bd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
---
title: resources.PostCSS
description: Processes the given resource with PostCSS using any PostCSS plugin.
categories: []
keywords: []
action:
  related:
    - functions/resources/Fingerprint
    - functions/resources/Minify
    - functions/resources/PostProcess
    - functions/css/Sass
  returnType: resource.Resource
  signatures: ['resources.PostCSS [OPTIONS] RESOURCE']
toc: true
expiryDate: 2025-06-24 # deprecated 2024-06-24
---

{{% deprecated-in 0.128.0 %}}
Use [css.PostCSS] instead.

[css.PostCSS]: /functions/css/postcss/
{{% /deprecated-in %}}

```go-html-template
{{ with resources.Get "css/main.css" | postCSS }}
  <link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
```

## Setup

Follow the steps below to transform CSS using any of the available [PostCSS plugins].

Step 1
: Install [Node.js].

Step 2
: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules:

```sh
npm i -D postcss postcss-cli autoprefixer
```

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:

```js
module.exports = {
  plugins: [
    require('autoprefixer')
  ]
};
```

{{% note %}}
{{% include "functions/resources/_common/postcss-windows-warning.md" %}}
{{% /note %}}

Step 4
: Place your CSS file within the `assets/css` directory.

Step 5
: Process the resource with PostCSS:

```go-html-template
{{ with resources.Get "css/main.css" | postCSS }}
  <link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
```

## Options

The `resources.PostCSS` method takes an optional map of options.

config
: (`string`) The directory that contains the PostCSS configuration file. Default is the root of the project directory.

noMap
: (`bool`) Default is `false`. If `true`, disables inline sourcemaps.

inlineImports
: (`bool`) Default is `false`. Enable inlining of @import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides.

skipInlineImportsNotFound
: (`bool`) Default is `false`. Before Hugo 0.99.0 when `inlineImports` was enabled and we failed to resolve an import, we logged it as a warning. We now fail the build. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set `skipInlineImportsNotFound` to true.

```go-html-template
{{ $opts := dict "config" "config-directory" "noMap" true }}
{{ with resources.Get "css/main.css" | postCSS $opts }}
  <link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
```

## No configuration file

To avoid using a PostCSS configuration file, you can specify a minimal configuration using the options map.

use
: (`string`) A space-delimited list of PostCSS plugins to use.

parser
: (`string`) A custom PostCSS parser.

stringifier
: (`string`) A custom PostCSS stringifier.

syntax
: (`string`) Custom postcss syntax.

```go-html-template
{{ $opts := dict "use" "autoprefixer postcss-color-alpha" }}
{{ with resources.Get "css/main.css" | postCSS $opts }}
  <link rel="stylesheet" href="{{ .RelPermalink }}">
{{ end }}
```

## Check environment

The current Hugo environment name (set by `--environment` or in configuration or OS environment) is available in the Node context, which allows constructs like this:

```js
const autoprefixer = require('autoprefixer');
const purgecss = require('@fullhuman/postcss-purgecss');
module.exports = {
  plugins: [
    autoprefixer,
    process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null
  ]
}
```

[node.js]: https://nodejs.org/en/download
[postcss plugins]: https://www.postcss.parts/
[supported file name]: https://github.com/postcss/postcss-load-config#usage
[transpile to CSS]: /functions/css/sass/