a-h · a-h · Dec 21, 2023 · Dec 17, 2023 · Dec 17, 2023 · Dec 21, 2023
diff --git a/.version b/.version
@@ -1 +1 @@
-0.2.499
+0.2.500
diff --git a/docs/docs/03-syntax-and-usage/14-using-with-go-templates.md b/docs/docs/03-syntax-and-usage/14-using-with-go-templates.md
@@ -0,0 +1,89 @@
+# Using with `html/template`
+
+Templ components can be used with the Go standard library [`html/template`](https://pkg.go.dev/html/template) package.
+
+## Using `html/template` in a templ component
+
+To use an existing `html/template` in a templ component, use the `templ.FromGoHTML` function.
+
+```templ title="component.templ"
+package testgotemplates
+
+import "html/template"
+
+var goTemplate = template.Must(template.New("example").Parse("<div>{{ . }}</div>"))
+
+templ Example() {
+	<!DOCTYPE html>
+	<html>
+		<body>
+			@templ.FromGoHTML(goTemplate, "Hello, World!")
+		</body>
+	</html>
+}
+```
+
+```go title="main.go"
+func main() {
+	Example.Render(context.Background(), os.Stdout)
+}
+```
+
+```html title="Output"
+<!DOCTYPE html>
+<html>
+	<body>
+		<div>Hello, World!</div>
+	</body>
+</html>
+```
+
+## Using a templ component with	`html/template`
+
+To use a templ component within a `html/template`, use the `templ.ToGoHTML` function to render the component into a `template.HTML value`.
+
+```templ title="component.html"
+package testgotemplates
+
+import "html/template"
+
+var example = template.Must(template.New("example").Parse(`<!DOCTYPE html>
+<html>
+	<body>
+		{{ . }}
+	</body>
+</html>
+`))
+
+templ greeting() {
+	<div>Hello, World!</div>
+}
+```
+
+```go title="main.go"
+func main() {
+	// Create the templ component.
+	templComponent := greeting()
+
+	// Render the templ component to a `template.HTML` value.
+	html, err := templ.ToGoHTML(context.Background(), templComponent)
+	if err != nil {
+		t.Fatalf("failed to convert to html: %v", err)
+	}
+
+	// Use the `template.HTML` value within the text/html template.
+	err = example.Execute(os.Stdout, html)
+	if err != nil {
+		t.Fatalf("failed to execute template: %v", err)
+	}
+}
+```
+
+```html title="Output"
+<!DOCTYPE html>
+<html>
+	<body>
+		<div>Hello, World!</div>
+	</body>
+</html>
+```
diff --git a/docs/docs/03-syntax-and-usage/15-rendering-raw-html.md b/docs/docs/03-syntax-and-usage/15-rendering-raw-html.md
@@ -0,0 +1,31 @@
+# Rendering raw HTML
+
+To render HTML that has come from a trusted source, bypassing all HTML escaping and security mechanisms that templ includes, use the `templ.Raw` function.
+
+:::info
+Only include HTML that comes from a trusted source.
+:::
+
+:::warning
+Use of this function may introduce security vulnerabilities to your program.
+:::
+
+```templ title="component.templ"
+templ Example() {
+	<!DOCTYPE html>
+	<html>
+		<body>
+			@templ.Raw("<div>Hello, World!</div>")
+		</body>
+	</html>
+}
+```
+
+```html title="Output"
+<!DOCTYPE html>
+<html>
+	<body>
+		<div>Hello, World!</div>
+	</body>
+</html>
+```
diff --git a/docs/docs/12-integrations/index.md b/docs/docs/12-integrations/index.md
@@ -15,3 +15,7 @@ https://github.com/a-h/templ/tree/main/examples/integration-gin
 An example of using templ with go-chi v5 can be found here: 
 
 https://github.com/a-h/templ/tree/main/examples/integration-chi
+
+## `template/html`
+
+See [Using with Go templates](../syntax-and-usage/using-with-go-templates)
diff --git a/generator/htmldiff/diff.go b/generator/htmldiff/diff.go
@@ -13,6 +13,41 @@ import (
 	"github.com/google/go-cmp/cmp"
 )
 
+func DiffStrings(expected, actual string) (diff string, err error) {
+	// Format both strings.
+	var wg sync.WaitGroup
+	wg.Add(2)
+
+	var errs []error
+
+	// Format expected.
+	go func() {
+		defer wg.Done()
+		e := new(strings.Builder)
+		err := htmlformat.Fragment(e, strings.NewReader(expected))
+		if err != nil {
+			errs = append(errs, fmt.Errorf("expected html formatting error: %w", err))
+		}
+		expected = e.String()
+	}()
+
+	// Format actual.
+	go func() {
+		defer wg.Done()
+		a := new(strings.Builder)
+		err := htmlformat.Fragment(a, strings.NewReader(actual))
+		if err != nil {
+			errs = append(errs, fmt.Errorf("actual html formatting error: %w", err))
+		}
+		actual = a.String()
+	}()
+
+	// Wait for processing.
+	wg.Wait()
+
+	return cmp.Diff(expected, actual), errors.Join(errs...)
+}
+
 func Diff(input templ.Component, expected string) (diff string, err error) {
 	return DiffCtx(context.Background(), input, expected)
 }

diff --git a/generator/test-go-template-in-templ/expected.html b/generator/test-go-template-in-templ/expected.html
@@ -0,0 +1,6 @@
+<!DOCTYPE html>
+<html>
+        <body>
+                <div>Hello, World!</div>
+	</body>
+</html>
diff --git a/generator/test-go-template-in-templ/render_test.go b/generator/test-go-template-in-templ/render_test.go
@@ -0,0 +1,22 @@
+package testgotemplates
+
+import (
+	_ "embed"
+	"testing"
+
+	"github.com/a-h/templ/generator/htmldiff"
+)
+
+//go:embed expected.html
+var expected string
+
+func TestExample(t *testing.T) {
+	component := Example()
+	diff, err := htmldiff.Diff(component, expected)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if diff != "" {
+		t.Error(diff)
+	}
+}
diff --git a/generator/test-go-template-in-templ/template.templ b/generator/test-go-template-in-templ/template.templ
@@ -0,0 +1,14 @@
+package testgotemplates
+
+import "html/template"
+
+var goTemplate = template.Must(template.New("example").Parse("<div>{{ . }}</div>"))
+
+templ Example() {
+	<!DOCTYPE html>
+	<html>
+		<body>
+			@templ.FromGoHTML(goTemplate, "Hello, World!")
+		</body>
+	</html>
+}
diff --git a/generator/test-go-template-in-templ/template_templ.go b/generator/test-go-template-in-templ/template_templ.go
diff --git a/generator/test-raw-elements/expected.html b/generator/test-raw-elements/expected.html
@@ -14,5 +14,6 @@
         }
     </script>
 		<h1>Hello</h1>
+                <div>World</div>
 	</body>
 </html>
diff --git a/generator/test-raw-elements/template.templ b/generator/test-raw-elements/template.templ
@@ -17,6 +17,7 @@ templ Example() {
         }
       </script>
 			<h1>Hello</h1>
+			@templ.Raw("<div>World</div>")
 		</body>
 	</html>
 }
diff --git a/generator/test-raw-elements/template_templ.go b/generator/test-raw-elements/template_templ.go
diff --git a/generator/test-templ-in-go-template/expected.html b/generator/test-templ-in-go-template/expected.html
@@ -0,0 +1,6 @@
+<!DOCTYPE html>
+<html>
+        <body>
+                <div>Hello, World!</div>
+	</body>
+</html>
diff --git a/generator/test-templ-in-go-template/render_test.go b/generator/test-templ-in-go-template/render_test.go
@@ -0,0 +1,39 @@
+package testgotemplates
+
+import (
+	"context"
+	_ "embed"
+	"strings"
+	"testing"
+
+	"github.com/a-h/templ"
+	"github.com/a-h/templ/generator/htmldiff"
+)
+
+//go:embed expected.html
+var expected string
+
+func TestExample(t *testing.T) {
+	// Create the templ component.
+	templComponent := greeting()
+	html, err := templ.ToGoHTML(context.Background(), templComponent)
+	if err != nil {
+		t.Fatalf("failed to convert to html: %v", err)
+	}
+
+	// Use it within the text/html template.
+	b := new(strings.Builder)
+	err = example.Execute(b, html)
+	if err != nil {
+		t.Fatalf("failed to execute template: %v", err)
+	}
+
+	// Compare the output with the expected.
+	diff, err := htmldiff.DiffStrings(expected, b.String())
+	if err != nil {
+		t.Fatalf("failed to diff strings: %v", err)
+	}
+	if diff != "" {
+		t.Error(diff)
+	}
+}
diff --git a/generator/test-templ-in-go-template/template.templ b/generator/test-templ-in-go-template/template.templ
@@ -0,0 +1,15 @@
+package testgotemplates
+
+import "html/template"
+
+var example = template.Must(template.New("example").Parse(`<!DOCTYPE html>
+<html>
+	<body>
+		{{ . }}
+	</body>
+</html>
+`))
+
+templ greeting() {
+	<div>Hello, World!</div>
+}