Add importContext option to css.Build, js.Build, css.Sass and css.TailwindCSS

This allows @import statements to be resolved in a set of user provided resources (e.g. from resources.FromString or css.ChromaStyles) before the assets filesystem.

The option also applies to css.PostCSS via the shared import inlining, and css.Sass requires the dartsass transpiler. The import context is part of the transformation cache key.

Fixes #15103

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

tpl/css/build_integration_test.go

@@ -731,3 +731,181 @@ body {
 		"--text-color: #333;",
 	)
 }
+
+func TestCSSBuildImportContext(t *testing.T) {
+	t.Parallel()
+
+	files := `
+-- hugo.toml --
+-- assets/foo.css --
+body { color: orange; }
+-- assets/css/main.css --
+@import "foo.css" screen;
+@import "bar.css" print;
+p {
+  font-color: red;
+}
+-- layouts/home.html --
+{{ $foo := resources.FromString "foo.css" "body { color: blue; }" }}
+{{ $bar := resources.FromString "bar.css" "body { color: green; }" }}
+{{/* resource.Resources implements the resources.ResourceGetter interface (the type of importContext). */}}
+{{ $resources := slice  $foo $bar}}
+{{ $opts := dict "minify" true "importContext" $resources }}
+{{ $css := resources.Get "css/main.css" | css.Build $opts }}
+CSS: {{ $css.RelPermalink }}|
+`
+
+	b := hugolib.Test(t, files, hugolib.TestOptOsFs())
+
+	b.AssertFileContent("public/css/main.css", `@media screen{body{color:#00f}}@media print{body{color:green}}p{font-color:red}`)
+}
+
+func TestCSSBuildImportContextChromaStyles(t *testing.T) {
+	t.Parallel()
+
+	files := `
+-- hugo.toml --
+disableKinds = ["taxonomy", "term", "rss", "sitemap", "section", "page"]
+[markup.highlight]
+style = "monokai"
+-- assets/css/components/all.css --
+@import "./chroma-light.css";
+@import "./chroma-dark.css" (prefers-color-scheme: dark);
+-- assets/css/main.css --
+@import "./components/all.css";
+
+:root {
+  color-scheme: light dark;
+}
+
+-- layouts/home.html --
+{{ $light := css.ChromaStyles (dict "targetPath" "css/components/chroma-light.css" "style" "github" "mode" "light") }}
+{{ $dark := css.ChromaStyles (dict "targetPath" "css/components/chroma-dark.css" "style" "github" "mode" "dark") }}
+{{ $opts := dict "minify" true "importContext" (slice $light $dark) }}
+{{ $css := resources.Get "css/main.css" | css.Build $opts }}
+CSS: {{ $css.RelPermalink }}|
+`
+
+	b := hugolib.Test(t, files, hugolib.TestOptOsFs())
+
+	b.AssertFileContent("public/index.html", "CSS: /css/main.css|")
+	b.AssertFileContent("public/css/main.css", ".bg{background-color:#f7f7f7}.chroma", "@media(prefers-color-scheme:dark){.bg{color:#e6edf3")
+}
+
+func TestCSSBuildImportContextHashes(t *testing.T) {
+	t.Parallel()
+
+	files := `
+-- hugo.toml --
+-- assets/foo.css --
+body { color: orange; }
+-- assets/css/main.css --
+@import "foo.css" screen;
+@import "bar.css" print;
+p {
+  font-color: red;
+}
+-- layouts/home.html --
+{{ $foo := resources.FromString "foo.css" "body { color: blue; }" }}|
+{{ $foo2 := resources.FromString "foo2.css" "body { color: blue; }" }}|
+{{ $foo3 := resources.FromString "foo.css" "body { color: indigo; }" }}|
+{{ $bar := resources.FromString "bar.css" "body { color: green; }" }}|
+{{ $resources := slice $foo $bar}}
+{{ $resourcesMount1 := $resources.Mount "a" "b"}}
+{{ $resourcesMount2 := $resources.Mount "a" "c"}}
+{{ $opts := dict "minify" true "importContext" $resources }}
+foo: {{ $foo | testinginternal.HashString }}|
+foo2: {{ $foo2 | testinginternal.HashString }}|
+foo3: {{ $foo3 | testinginternal.HashString }}|
+bar: {{ $bar | testinginternal.HashString }}|
+resources: {{ $resources | testinginternal.HashString }}|
+resourcesMount1: {{ $resourcesMount1 | testinginternal.HashString }}|
+resourcesMount2: {{ $resourcesMount2 | testinginternal.HashString }}|
+resources namespace: {{ resources | testinginternal.HashString }}|
+opts: {{ $opts | testinginternal.HashString }}|
+home: {{ . | testinginternal.HashString }}|{{ .Key }}|
+slice with Page: {{ slice $foo $bar . | testinginternal.HashString }}|
+map with Page: {{ dict "foo" $foo "bar" $bar "page" . | testinginternal.HashString }}|
+{{ $css := resources.Get "css/main.css" | css.Build $opts -}}
+css: {{ $css | testinginternal.HashString }}|
+cached1: {{ testinginternal.NewCachedResourceGetter $resources resources | testinginternal.HashString}}
+cached2: {{ testinginternal.NewCachedResourceGetter $resources | testinginternal.HashString}}
+cached3: {{ testinginternal.NewCachedResourceGetter $resources resources $resourcesMount1 $resourcesMount2 | testinginternal.HashString}}
+
+
+`
+
+	for range 2 {
+
+		b := hugolib.Test(t, files, hugolib.TestOptOsFs())
+
+		b.AssertFileContent("public/index.html", `
+foo: 17610550322594361312|
+foo2: 12741631597870435822|
+foo3: 4488319114298108946|
+bar: 11981658863051989001|
+resources: 10963320145636139629|
+resourcesMount1: 7843365040860281860|
+resourcesMount2: 10632811173795339581|
+resources namespace: 12714111578321948564|
+opts: 7538269917289793785|
+css: 8075855322897706813|
+home: 166103792234269065|/html|
+slice with Page: 7769684332502419906|
+map with Page: 10393165700333352395|
+cached1: 7064840587060576200
+cached2: 6730658186132701788
+cached3: 13761938017162285970
+`)
+
+	}
+}
+
+func TestCSSBuildImportContextEdit(t *testing.T) {
+	t.Parallel()
+
+	files := `
+-- hugo.toml --
+disableLiveReload = true
+-- assets/css/common/baz.css --
+body { color: purple; }
+-- assets/css/main.css --
+@import "foo.css" screen;
+@import "bar.css" print;
+@import "baz.css" screen and (min-width: 768px);
+p {
+  font-color: red;
+}
+-- layouts/home.html --
+{{ $foo := resources.FromString "foo.css" "body { color: blue; }" }}
+{{ $bar := resources.FromString "bar.css" "body { color: green; }" }}
+{{ $common := resources.Match "/css/common/*.css" }}
+{{ $commonMount := ($common.Mount "/css/common" ".")}}
+{{ $resources := slice $foo $bar }}
+{{ $opts := dict "minify" true "importContext" (slice $resources $commonMount) }}
+resources: {{ $resources | testinginternal.HashString }}|
+{{ $css := resources.Get "css/main.css" | css.Build $opts }}
+CSS: {{ $css.RelPermalink }}|
+`
+
+	b := hugolib.TestRunning(t, files, hugolib.TestOptOsFs())
+
+	b.AssertFileContent("public/css/main.css", `
+@media screen{body{color:#00f}}@media print{body{color:green}}
+@media screen and (min-width:768px){body{color:purple}}
+`)
+
+	// Edit resource built with resources.FromString.
+	b.EditFileReplaceAll("layouts/home.html", "color: green", "color: yellow").Build()
+	b.AssertFileContent("public/css/main.css", `
+@media screen{body{color:#00f}}@media print{body{color:#ff0}}
+@media screen and (min-width:768px){body{color:purple}}
+`)
+
+	// Edit resource in the mounted slice.
+	b.EditFileReplaceAll("assets/css/common/baz.css", "purple", "orange").Build()
+	b.AssertFileContent("public/css/main.css", `
+@media screen{body{color:#00f}}@media print{body{color:#ff0}}
+@media screen and (min-width:768px){body{color:orange}}
+`)
+}

tpl/resources/resources.go

@@ -58,7 +58,10 @@ func New(deps *deps.Deps) (*Namespace, error) {
 	}, nil
 }
 
-var _ resource.ResourceFinder = (*Namespace)(nil)
+var (
+	_ resource.ResourceFinder = (*Namespace)(nil)
+	_ resource.Identifier     = (*Namespace)(nil)
+)
 
 // Namespace provides template functions for the "resources" namespace.
 type Namespace struct {
@@ -300,3 +303,8 @@ func (ns *Namespace) PostProcess(r resource.Resource) (postpub.PostPublishedReso
 	hugo.DeprecateWithLogger("resources.PostProcess", "Use templates.Defer instead. See https://gohugo.io/functions/templates/defer/", "v0.164.0", ns.deps.Log.Logger())
 	return ns.deps.ResourceSpec.PostProcess(r)
 }
+
+// For internal use only.
+func (ns *Namespace) Key() string {
+	return "tpl.resources"
+}

tpl/testinginternal/init.go

@@ -0,0 +1,38 @@
+// Copyright 2026 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 testinginternal
+
+import (
+	"context"
+
+	"github.com/gohugoio/hugo/deps"
+	"github.com/gohugoio/hugo/tpl/internal"
+)
+
+const name = "testinginternal"
+
+func init() {
+	f := func(d *deps.Deps) *internal.TemplateFuncsNamespace {
+		ctx := New(d)
+
+		ns := &internal.TemplateFuncsNamespace{
+			Name:    name,
+			Context: func(cctx context.Context, args ...any) (any, error) { return ctx, nil },
+		}
+
+		return ns
+	}
+
+	internal.AddTemplateFuncsNamespace(f)
+}

tpl/testinginternal/testinginternal.go

@@ -0,0 +1,41 @@
+// Copyright 2026 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 testinginternal provides template functions for internal use.
+// //  These should not be used in user templates, as they are not guaranteed to be stable or even useful.
+package testinginternal
+
+import (
+	"github.com/gohugoio/hugo/common/hashing"
+	"github.com/gohugoio/hugo/deps"
+	"github.com/gohugoio/hugo/resources/resource"
+)
+
+// New returns a new instance of the testinginternal-namespaced template functions.
+func New(d *deps.Deps) *Namespace {
+	ns := &Namespace{}
+
+	return ns
+}
+
+// Namespace provides template functions for the "testinginternal" namespace.
+type Namespace struct{}
+
+// HashString wraps the core hashing func used for e.g. calculating resource transformation keys.
+func (ns *Namespace) HashString(args ...any) string {
+	return hashing.HashString(args...)
+}
+
+func (ns *Namespace) NewCachedResourceGetter(args ...any) resource.ResourceGetter {
+	return resource.NewCachedResourceGetter(args...)
+}

tpl/tplimplinit/tplimplinit.go

@@ -49,6 +49,7 @@ import (
 	_ "github.com/gohugoio/hugo/tpl/site"
 	_ "github.com/gohugoio/hugo/tpl/strings"
 	_ "github.com/gohugoio/hugo/tpl/templates"
+	_ "github.com/gohugoio/hugo/tpl/testinginternal"
 	_ "github.com/gohugoio/hugo/tpl/time"
 	_ "github.com/gohugoio/hugo/tpl/transform"
 	_ "github.com/gohugoio/hugo/tpl/urls"