tocss: Add vars option

This commit adds a new `vars` option to both the Sass transpilers (Dart Sass and Libsass).

This means that you can pass a map with key/value pairs to the transpiler:

```handlebars
{{ $vars := dict "$color1" "blue" "$color2" "green" "$font_size" "24px" }}
{{ $cssOpts := (dict "transpiler" "dartsass" "outputStyle" "compressed" "vars" $vars ) }}
{{ $r := resources.Get "scss/main.scss" |  toCSS $cssOpts }}
```

And the the variables will be available in the `hugo:vars` namespace. Example usage for Dart Sass:

```scss
@use "hugo:vars" as v;

p {
    color: v.$color1;
    font-size: v.$font_size;
}
```

Note that Libsass does not support the `use` keyword, so you need to `import` them as global variables:

```scss
@import "hugo:vars";

p {
    color: $color1;
    font-size: $font_size;
}
```

Hugo will:

* Add a missing leading `$` for the variable names if needed.
* Wrap the values in `unquote('VALUE')` (Sass built-in) to get proper handling of identifiers vs other strings.

This means that you can pull variables directly from e.g. the site config:

```toml
[params]
[params.sassvars]
color1 = "blue"
color2 = "green"
font_size = "24px"
image = "images/hero.jpg"
```

```handlebars
{{ $vars := site.Params.sassvars}}
{{ $cssOpts := (dict "transpiler" "dartsass" "outputStyle" "compressed" "vars" $vars ) }}
{{ $r := resources.Get "scss/main.scss" |  toCSS $cssOpts }}
```

Fixes #10555

1 files changed, 48 insertions, 0 deletions

diff --git a/resources/resource_transformers/tocss/internal/sass/helpers.go b/resources/resource_transformers/tocss/internal/sass/helpers.go
new file mode 100644
index 000000000..8128fd4d7
--- /dev/null
+++ b/resources/resource_transformers/tocss/internal/sass/helpers.go
@@ -0,0 +1,48 @@
+// Copyright 2022 The Hugo Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package sass
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+const (
+	HugoVarsNamespace = "hugo:vars"
+)
+
+func CreateVarsStyleSheet(vars map[string]string) string {
+	if vars == nil {
+		return ""
+	}
+	var varsStylesheet string
+
+	var varsSlice []string
+	for k, v := range vars {
+		var prefix string
+		if !strings.HasPrefix(k, "$") {
+			prefix = "$"
+		}
+		// These variables can be a combination of Sass identifiers (e.g. sans-serif), which
+		// should not be quoted, and URLs et, which should be quoted.
+		// unquote() is knowing what to do with each.
+		varsSlice = append(varsSlice, fmt.Sprintf("%s%s: unquote('%s');", prefix, k, v))
+	}
+	sort.Strings(varsSlice)
+	varsStylesheet = strings.Join(varsSlice, "\n")
+
+	return varsStylesheet
+
+}