Postcss, config option: unclear documentation

support
1

From the official documentation for function resources.PostCSS:

Options
config [string]
    Set a custom directory to look for a config file

I define a custom directory as option:

{{ with ( resources.Get "test.scss" ) | postCSS  (dict "config" "mydir/" ) }}

and it correctly picks up postcss.config.js from mydir. So far so good.

Documentation also tells:

The resource will be processed using the project’s or theme’s
own postcss.config.js or any file set with the config option.

This makes me think I can specify a file as value in the config option. So I try with:

{{ with ( resources.Get "test.scss" ) | postCSS  (dict "config" "mydir/mypostcss.config.js" ) }}

This doesn’t thow an error, but doesn’t pick up mypostcss.config.js either.
Can I specify both a directory and a file with the config option?

hugo’s error message when specifying an invalid file/path isn’t really helpful here:

POSTCSS: failed to transform "a.scss" (text/x-scss): postcss config "path" not found:

Side note: I consider the config option somehow unfortunate, would be better to have a configDir (or a configFile) option here. But that ship has probably sailed already!?

2

The Hugo config option corresponds to the postcss-cli --config option. While our naming may not be ideal for Hugo users, it makes sense in this context.

$ ./node_modules/.bin/postcss --help
--config  Set a custom directory to look for a config file

There is not an option to specify a file name.

postcss-cli loads the config file using postcss-load-config, which allows you to use file names other than postcss.config.js, but your options are limited. You cannot use an arbitrary file name:

https://github.com/postcss/postcss-load-config/blob/main/src/index.js#L81-L94

I think there are two Hugo issues:

1) Fix the silent failure, or report upstream if appropriate (issue #10846)

2) Update the documentation (issue #2005)

  • Consistently use the word “directory” instead of “file” when referring to the config option
  • State that the default config directory is the project root
  • State that postcss.config.js is the default file name
  • State that you cannot use an arbitrary file name, with a link to the list of acceptable file names