Article spinning and spintax/spinning syntax engine, useful for A/B, testing pieces of text/articles and creating more natural conversations.

gospin

Goview is a lightweight, minimalist and idiomatic template library based on golang html/template for building Go web application

goview

Go implementation of Shopify Liquid templates

liquid

Useful template functions for Go templates

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset=".github/profile/images/logo_landing_light.png">
    <source media="(prefers-color-scheme: light)" srcset=".github/profile/images/logo_landing_dark.png">
    <img alt="Sprout Logo" width="700" src="">
  </picture>
  <hr />
</div>

<div align="center">
<a target="_blank" href="https://github.com/go-sprout/sprout/actions/workflows/test.yaml"><img src="https://img.shields.io/github/actions/workflow/status/go-sprout/sprout/test.yaml?branch=main&label=tests"></a>
<a target="_blank" href="https://goreportcard.com/report/github.com/go-sprout/sprout"><img src="https://goreportcard.com/badge/github.com/go-sprout/sprout" /></a>
<a target="_blank" href="https://codeclimate.com/github/go-sprout/sprout"><img alt="Code Climate maintainability" src="https://img.shields.io/codeclimate/maintainability/go-sprout/sprout"></a>
<a target="_blank" href="https://codecov.io/gh/go-sprout/sprout"><img alt="Codecov" src="https://img.shields.io/codecov/c/github/go-sprout/sprout"></a>
<img src="https://img.shields.io/github/v/release/go-sprout/sprout?label=last%20release" alt="GitHub release (latest by date)">
<img src="https://img.shields.io/github/contributors/go-sprout/sprout?color=blueviolet" alt="GitHub contributors">
<img src="https://img.shields.io/github/stars/go-sprout/sprout?style=flat&color=blueviolet" alt="GitHub Repo stars">
<a target="_blank" href="https://pkg.go.dev/github.com/go-sprout/sprout"><img src="https://pkg.go.dev/badge/github.com/go-sprout/sprout.svg" alt="Go Reference"></a>
<br />
<h3> <a target="_blank" href="https://docs.atom.codes/sprout">Official Documentation</a></h3>
<hr/>
</div>

> [!NOTE]
> Sprout is an evolved variant of the [Masterminds/sprig](https://github.com/Masterminds/sprig) library, reimagined for modern Go versions. It introduces fresh functionalities and commits to maintaining the library, picking up where Sprig left off. Notably, Sprig had not seen updates for two years and was not compatible beyond Golang 1.13, necessitating the creation of Sprout.

## Motivation

Sprout was born out of the need for a modernized, maintained, and performant template function library. Sprig, the predecessor to Sprout, had not seen updates for two years and was not optimized for later versions of Golang. Sprout aims to fill this gap by providing a library that is actively maintained, compatible with the latest Go versions, and optimized for performance.

## Roadmap to Sprout v1.0

You can track our progress towards Sprout v1.0 by following the documentation page
[here](https://docs.atom.codes/sprout/roadmap-to-sprout-v1.0).

## Table of Contents

- [Motivation](#motivation)
- [Roadmap to Sprout v1.0](#roadmap-to-sprout-v10)
- [Transitioning from Sprig](#transitioning-from-sprig)
- [Usage](#usage)
  - [Creating a Handler](#creating-a-handler)
  - [Customizing the Handler](#customizing-the-handler)
  - [Working with Registries](#working-with-registries)
  - [Working with Registries Groups](#working-with-registries-groups)
  - [Building Function Maps](#building-function-maps)
  - [Working with Templates](#working-with-templates)
- [Usage: Quick Example (code only)](#usage-quick-example)
- [Performance Benchmarks](#performance-benchmarks)
  - [Sprig v3.2.3 vs Sprout v0.5](#sprig-v323-vs-sprout-v05)
- [Development Philosophy (Currently in reflexion to create our)](#development-philosophy-currently-in-reflexion-to-create-our)


## Transitioning from Sprig

Sprout provide a package `sprigin` to provide a drop-in replacement for Sprig in the v1.0, with the same function names and behavior. To use Sprout in your project, simply replace the Sprig import with sprigin:

> [!IMPORTANT]
> The `sprigin` package is a temporary solution to provide backward compatibility with Sprig. We recommend updating your code to use the Sprout package directly to take advantage of the new features and improvements.
>
> A complete guide is available in the [documentation](https://docs.atom.codes/sprout/migration-from-sprig).

```diff
import (
-  "github.com/Masterminds/sprig/v3"
+  "github.com/go-sprout/sprout/sprigin"
)

tpl := template.Must(
  template.New("base").
-   Funcs(sprig.FuncMap()).
+   Funcs(sprigin.FuncMap()).
    ParseGlob("*.tmpl")
)
```

## Usage

### Creating a Handler
A handler in Sprout is responsible for managing the function registries and functions. The DefaultHandler is the primary implementation provided by Sprout.

```go
import "github.com/go-sprout/sprout"

handler := sprout.New()
``` 

### Customizing the Handler

Sprout supports various customization options using handler options:

```go
handler := sprout.New(
  // Add your logger to the handler to log errors and debug information using the
  // standard slog package or any other logger that implements the slog.Logger interface.
  // By default, Sprout uses a slog.TextHandler.
  sprout.WithLogger(slogLogger),
  // Set the alias for a function. By default, Sprout use alias for some functions for backward compatibility with Sprig.
  sprout.WithAlias("hello", "hi"),
)
```

### Working with Registries
Registries in Sprout are groups of functions that can be added to a handler. They help organize functions and optimize template performance.

You can retrieve all built-in registries and functions under [Registries](https://docs.atom.codes/sprout/registries/list-of-all-registries).

```go
import (
  "github.com/go-sprout/sprout/registry/conversion" // toString, toInt, toBool, ...
  "github.com/go-sprout/sprout/registry/std" // default, empty, any, all, ...
)

//...

handler.AddRegistries(
  conversion.NewRegistry(),
  std.NewRegistry(),
)
```

### Working with Registries Groups
In some cases, you can use a group of registries to add multiple registries at once.

You can retrieve all built-in registries groups under [Registry Groups](https://docs.atom.codes/sprout/groups/list-of-all-registry-groups).

```go
import (
  "github.com/go-sprout/sprout/group/all"
)

//...

handler.AddGroup(
  all.RegistryGroup(),
)
```

### Building Function Maps

To use Sprout with templating engines like `html/template` or `text/template`, you need to build the function map:
```go
funcs := handler.Build()
tpl := template.New("example").Funcs(funcs).Parse(`{{ hello }}`)
```

### Working with Templates
Once your function map is ready, you can use it to render templates:
```go
tpl, err := template.New("example").Funcs(funcs).Parse(`{{ myFunc }}`)
if err != nil {
    log.Fatal(err)
}
tpl.Execute(os.Stdout, nil)
``` 
This will render the template with all functions and aliases available.


## Usage: Quick Example 

Here is a quick example of how to use Sprout with the `text/template` package:
```go
package main

import (
	"os"
	"text/template"

	"github.com/go-sprout/sprout"
	"github.com/go-sprout/sprout/registry/std"
)

func main() {
	handler := sprout.New()
	handler.AddRegistry(std.NewRegistry())

	tpl := template.Must(
    template.New("example").Funcs(handler.Build()).Parse(`{{ hello }}`),
  )
	tpl.Execute(os.Stdout, nil)
}
```

## Performance Benchmarks

To see all the benchmarks, please refer to the [benchmarks](benchmarks/README.md) directory.

## Sprig v3.2.3 vs Sprout v0.5
```
goos: linux
goarch: amd64
pkg: sprout_benchmarks
cpu: Intel(R) Core(TM) i9-9900K CPU @ 3.60GHz
BenchmarkSprig-16              1        2991811373 ns/op        50522680 B/op      32649 allocs/op
BenchmarkSprout-16             1        1638797544 ns/op        42171152 B/op      18061 allocs/op
PASS
ok      sprout_benchmarks       4.921s
```

**Time improvement**: ((2991811373 - 1638797544) / 2991811373) * 100 = 45.3%
**Memory improvement**: ((50522680 - 42171152) / 50522680) * 100 = 16.5%

So, Sprout v0.5 is approximately 45.3% faster and uses 16.5% less memory than Sprig v3.2.3. 🚀

You can see the full benchmark results [here](benchmarks/README.md).

## Development Philosophy (Currently in consideration to create ours)

Our approach to extending and refining Sprout was guided by several key principles:

- Build on the principles of simplicity, flexibility, and consistency. 
- Empower developers to create robust templates without sacrificing performance or usability. 
- Adheres strictly to Go's templating conventions, ensuring a seamless experience for those familiar with Go's native tools.
- Naming conventions across functions are standardized for predictability and ease of use.
- Emphasizes error handling, preferring to safe defaults over panics.
- Provide a clear and comprehensive documentation to help users understand the library and its features.
- Maintain a high level of code quality, ensuring that the library is well-tested, performant, and reliable.
- Continuously improve and optimize the library to meet the needs of the community.
- Avoids any external dependencies within template functions, ensuring all operations are self-contained and reliable.
- Performance is a key consideration, with a focus on optimizing the library for speed and efficiency.


sprout

HTML/CSS to PDF rendering with TeX-quality typesetting in pure Go

# bagme - boxes and glue made easy

bagme is a Go library that renders HTML/CSS to PDF using the [boxes and glue](https://boxesandglue.dev) typesetting engine.
It implements TeX's line-breaking and page-breaking algorithms, so you get high-quality typesetting with almost no effort.

## Installation

```bash
go get github.com/boxesandglue/bagme
```

## Render a complete HTML document

Use `RenderPages` for automatic page breaks, `@page` margins, and multi-page output:

```go
package main

import (
	"log"

	"github.com/boxesandglue/bagme/document"
)

func main() {
	d, err := document.New("output.pdf")
	if err != nil {
		log.Fatal(err)
	}
	d.AddCSS(`
		@page { size: A4; margin: 2cm; }
		body { font-family: serif; font-size: 11pt; line-height: 1.4; }
		h1 { page-break-before: always; }
	`)
	if err := d.RenderPages(`
		<h1>Chapter 1</h1>
		<p>In olden times when wishing still helped one, there lived a king
		whose daughters were all beautiful...</p>

		<h1>Chapter 2</h1>
		<p>Close by the king's castle lay a great dark forest, and under an
		old lime-tree in the forest was a well...</p>
	`); err != nil {
		log.Fatal(err)
	}
	if err := d.Finish(); err != nil {
		log.Fatal(err)
	}
}
```

## Place HTML snippets at exact positions

Use `OutputAt` for precise placement on a page (labels, forms, letterheads):

```go
package main

import (
	"log"

	"github.com/boxesandglue/bagme/document"
	"github.com/boxesandglue/boxesandglue/backend/bag"
)

func main() {
	d, err := document.New("out.pdf")
	if err != nil {
		log.Fatal(err)
	}
	d.AddCSS(`body { font-family: serif; font-size: 12pt; }`)

	ps, _ := d.PageSize()
	w := ps.ContentWidth
	x := ps.MarginLeft
	y := ps.Height - ps.MarginTop

	d.OutputAt("<h1>Hello, World!</h1><p>Placed at exact coordinates.</p>", w, x, y)
	d.Finish()
}
```

## Features

- Automatic page breaks with CSS `@page` rules
- `page-break-before` / `page-break-after` (always, avoid)
- Page margin boxes (`@top-center`, `@bottom-right`, etc.) for headers/footers
- CSS styling: fonts, colors, margins, padding, borders (rounded), backgrounds
- Tables with colspan/rowspan, borders, and cell backgrounds
- Ordered and unordered lists
- Images (PDF, PNG) and inline SVG
- OpenType features and variable fonts via `font-feature-settings` / `font-variation-settings`
- TeX-quality line breaking (Knuth-Plass algorithm)
- Heading extraction for table of contents generation
- Pure Go — no C dependencies, no browser, single binary

## Limitations

* No automatic page breaks within a single paragraph (breaks happen between block elements)
* Limited CSS support compared to a full browser engine
* No floats or flexbox/grid layout

## Contact

Contact: <gundlach@speedata.de><br>
License: New BSD License<br>
Status: Beta — API may change.<br>
Mastodon: [boxesandglue@typo.social](https://typo.social/@boxesandglue)


bagme

A Go code generator inspired by Hero and Fasttemplate. Has include files, custom tag definitions, injected Go code, language translation, and more

A maroto way to create PDFs. Maroto is inspired in Bootstrap and uses gofpdf. Fast and simple

# Maroto V2

[![GoDoc](https://godoc.org/github.com/johnfercher/maroto?status.svg)](https://pkg.go.dev/github.com/johnfercher/maroto/v2)
[![Go Report Card](https://goreportcard.com/badge/github.com/johnfercher/maroto)](https://goreportcard.com/report/github.com/johnfercher/maroto)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#template-engines)  
[![CI](https://github.com/johnfercher/maroto/actions/workflows/goci.yml/badge.svg)](https://github.com/johnfercher/maroto/actions/workflows/goci.yml)
[![Lint](https://github.com/johnfercher/maroto/actions/workflows/golangci-lint.yml/badge.svg)](https://github.com/johnfercher/maroto/actions/workflows/golangci-lint.yml)
[![Codecov](https://img.shields.io/codecov/c/github/johnfercher/maroto)](https://codecov.io/gh/johnfercher/maroto)
[![Visits Badge](https://badges.pufler.dev/visits/johnfercher/maroto)](https://badges.pufler.dev)
[![Stars Badge](https://img.shields.io/github/stars/johnfercher/maroto.svg?style=social&label=Stars)](https://github.com/johnfercher/maroto/stargazers)


A Maroto way to create PDFs. Maroto is inspired in Bootstrap and uses [Gofpdf](https://github.com/phpdave11/gofpdf). Fast and simple.

![sirmaroto](docs/assets/images/logosmall.png)
> Maroto definition: Brazilian expression, means an astute/clever/intelligent person. 
> [Art by **@marinabankr**](https://www.instagram.com/marinabankr/)

You can write your PDFs like you are creating a site using Bootstrap. A Row may have many Cols, and a Col may have many components. 
Besides that, pages will be added when content may extrapolate the useful area. You can define a header which will be added
always when a new page appear, in this case, a header may have many rows, lines or tablelist. 

#### Maroto `v2.4.0` is here! Try out:

* Installation with`go get`:

```bash
go get github.com/johnfercher/maroto/v2@v2.4.0
```

* You can see the full `v2` documentation [here](https://maroto.tech/#/README?id=maroto-v2).
* The `v1` still exists in [this branch](https://github.com/johnfercher/maroto/tree/v1), and you can see the doc [here]([https://maroto.io/#/v1/README?id=deprecated](https://maroto.tech/#/v1/README?id=deprecated)).

![result](docs/assets/images/result.png)

## Contributing

| Command         | Description                                       | Dependencies                                                  |
|-----------------|---------------------------------------------------|---------------------------------------------------------------|
| `make build`    | Build project                                     | `go`                                                          |
| `make test`     | Run unit tests                                    | `go`                                                          |
| `make fmt`      | Format files                                      | `gofmt`, `gofumpt` and `goimports`                            |
| `make lint`     | Check files                                       | `golangci-lint`                                               |
| `make dod`      | (Definition of Done) Format files and check files | Same as `make build`, `make test`, `make fmt` and `make lint` | 
| `make install`  | Install all dependencies                          | `go`, `curl` and `git`                                        |
| `make examples` | Run all examples                                  | `go`                                                          |
| `make mocks`    | Generate mocks                                    | `go` and `mockery`                                            |
| `make docs`     | Run docsify docs server local                     | `docsify`                                                     |
| `make godoc`    | Run godoc server local                            | `godoc`                                                       |

## Stargazers over time
[![Stargazers over time](https://starchart.cc/johnfercher/maroto.svg?variant=adaptive)](https://starchart.cc/johnfercher/maroto)


maroto

# [pongo](https://en.wikipedia.org/wiki/Pongo_%28genus%29)2

[![PkgGoDev](https://pkg.go.dev/badge/github.com/flosch/pongo2/v7)](https://pkg.go.dev/github.com/flosch/pongo2/v7)
[![Build Status](https://schlachterinf.semaphoreci.com/badges/pongo2/branches/master.svg?style=shields&key=4ecde757-d6dd-4db2-8998-c84f55253d8f)](https://schlachterinf.semaphoreci.com/projects/pongo2)
[![Run on Repl.it](https://repl.it/badge/github/flosch/pongo2)](https://repl.it/github/flosch/pongo2)

pongo2 is a Django-syntax like templating-language ([official website](https://pongo2.dev/)).

Install/update using `go get` (no dependencies required by pongo2):

```sh
go get -u github.com/flosch/pongo2/v7
```

Please use the [issue tracker](https://github.com/flosch/pongo2/issues) if you're encountering any problems with pongo2 or if you need help with implementing tags or filters ([create a ticket!](https://github.com/flosch/pongo2/issues/new)).

:question: [**Looking for a Go developer/consultant?** I'm available for hire. :man_technologist:](mailto:florian@schlachter.tech )

## First impression of a template

```django
<html>
  <head>
    <title>Our admins and users</title>
  </head>
  {# This is a short example to give you a quick overview of pongo2's syntax. #}
  {% macro user_details(user, is_admin=false) %}
  <div class="user_item">
    
    <h2 {% if (user.karma>= 40) || (user.karma > calc_avg_karma(userlist)+5) %} class="karma-good"{% endif %}>

      
      {{ user }}
    </h2>

    
    <p>This user registered {{ user.register_date|naturaltime }}.</p>

    
    <p>The user's biography:</p>
    <p>
      {{ user.biography|markdown|truncatewords_html:15 }}
      <a href="/user/{{ user.id }}/">read more</a>
    </p>

    {% if is_admin %}
    <p>This user is an admin!</p>
    {% endif %}
  </div>
  {% endmacro %}

  <body>
    

    <h1>Our admins</h1>
    {% for admin in adminlist %} {{ user_details(admin, true) }} {% endfor %}

    <h1>Our members</h1>
    {% for user in userlist %} {{ user_details(user) }} {% endfor %}
  </body>
</html>
```

## Documentation

- [Getting Started](docs/getting-started.md) - Installation, basic usage, and first steps
- [Template Syntax](docs/template-syntax.md) - Variables, expressions, operators, and comments
- [Filters Reference](docs/filters.md) - Complete list of all built-in filters
- [Tags Reference](docs/tags.md) - Complete list of all built-in tags
- [Macros](docs/macros.md) - Reusable template fragments with arguments
- [Template Sets](docs/template-sets.md) - Loaders, caching, globals, and sandbox features
- [Security and Sandboxing](docs/security-sandboxing.md) - Autoescape, sandboxing, and security best practices
- [Custom Extensions](docs/custom-extensions.md) - Creating your own filters and tags
- [Changelog](CHANGELOG.md) - Version history and release notes

## Features

- Syntax- and feature-set-compatible with [Django templates](https://docs.djangoproject.com/en/stable/topics/templates/)
- [Advanced C-like expressions](https://github.com/flosch/pongo2/blob/master/template_tests/expressions.tpl).
- [Complex function calls within expressions](https://github.com/flosch/pongo2/blob/master/template_tests/function_calls_wrapper.tpl).
- [Easy API to create new filters and tags](https://pkg.go.dev/github.com/flosch/pongo2/v7#RegisterFilter) ([including parsing arguments](https://pkg.go.dev/github.com/flosch/pongo2/v7#Parser))
- Additional features:
  - Macros including importing macros from other files (see [template_tests/macro.tpl](https://github.com/flosch/pongo2/blob/master/template_tests/macro.tpl))
  - [Template sandboxing](https://pkg.go.dev/github.com/flosch/pongo2/v7#TemplateSet) ([directory patterns](http://golang.org/pkg/path/filepath/#Match), banned tags/filters)

## Caveats

### Filters

- **date** / **time**: The `date` and `time` filter are taking the Golang specific time- and date-format (not Django's one) currently. [Take a look on the format here](http://golang.org/pkg/time/#Time.Format).
- **stringformat**: `stringformat` does **not** take Python's string format syntax as a parameter, instead it takes Go's. Essentially `{{ 3.14|stringformat:"pi is %.2f" }}` is `fmt.Sprintf("pi is %.2f", 3.14)`.
- **escape** / **force_escape**: Unlike Django's behaviour, the `escape`-filter is applied immediately. Therefore there is no need for a `force_escape`-filter yet.

### Tags

- **for**: All the `forloop` fields (like `forloop.counter`) are written with a capital letter at the beginning. For example, the `counter` can be accessed by `forloop.Counter` and the parentloop by `forloop.Parentloop`.
- **now**: takes Go's time format (see **date** and **time**-filter).

### Misc

- **not in-operator**: You can check whether a map/struct/string contains a key/field/substring by using the in-operator (or the negation of it):
  `{% if key in map %}Key is in map{% else %}Key not in map{% endif %}` or `{% if !(key in map) %}Key is NOT in map{% else %}Key is in map{% endif %}`.

## Add-ons, libraries and helpers

### Official

- [pongo2-addons](https://github.com/flosch/pongo2-addons) - Official additional filters/tags for pongo2 (for example a **markdown**-filter). They are in their own repository because they're relying on 3rd-party-libraries.

### 3rd-party

- [beego-pongo2](https://github.com/oal/beego-pongo2) - A tiny little helper for using Pongo2 with [Beego](https://github.com/astaxie/beego).
- [beego-pongo2.v2](https://github.com/ipfans/beego-pongo2.v2) - Same as `beego-pongo2`, but for pongo2 v2.
- [macaron-pongo2](https://github.com/macaron-contrib/pongo2) - pongo2 support for [Macaron](https://github.com/Unknwon/macaron), a modular web framework.
- [ginpongo2](https://github.com/ngerakines/ginpongo2) - middleware for [gin](github.com/gin-gonic/gin) to use pongo2 templates
- [Build'n support for Iris' template engine](https://github.com/kataras/iris)
- [pongo2gin](https://gitlab.com/go-box/pongo2gin) - alternative renderer for [gin](github.com/gin-gonic/gin) to use pongo2 templates
- [pongo2-trans](https://github.com/digitalcrab/pongo2trans) - `trans`-tag implementation for internationalization
- [tpongo2](https://github.com/tango-contrib/tpongo2) - pongo2 support for [Tango](https://github.com/lunny/tango), a micro-kernel & pluggable web framework.
- [p2cli](https://github.com/wrouesnel/p2cli) - command line templating utility based on pongo2
- [pongorenderer](https://github.com/siredwin/pongorenderer) - minimal pongo2 renderer for [Echo](https://github.com/labstack/echo) web framework
- [pongo2gcloud](https://github.com/dieselburner/pongo2gcloud) - Google Cloud Storage loader for pongo2 template files

Please add your project to this list and send me a pull request when you've developed something nice for pongo2.

## Who's using pongo2

[I'm compiling a list of pongo2 users](https://github.com/flosch/pongo2/issues/241). Add your project or company!

## API-usage examples

Please see the documentation for a full list of provided API methods.

### A tiny example (template string)

```go
// Compile the template first (i. e. creating the AST)
tpl, err := pongo2.FromString("Hello {{ name|capfirst }}!")
if err != nil {
    panic(err)
}
// Now you can render the template with the given
// pongo2.Context how often you want to.
out, err := tpl.Execute(pongo2.Context{"name": "florian"})
if err != nil {
    panic(err)
}
fmt.Println(out) // Output: Hello Florian!
```

## Example server-usage (template file)

```go
package main

import (
    "github.com/flosch/pongo2/v7"
    "net/http"
)

// Pre-compiling the templates at application startup using the
// little Must()-helper function (Must() will panic if FromFile()
// or FromString() will return with an error - that's it).
// It's faster to pre-compile it anywhere at startup and only
// execute the template later.
var tplExample = pongo2.Must(pongo2.FromFile("example.html"))

func examplePage(w http.ResponseWriter, r *http.Request) {
    // Execute the template per HTTP request
    err := tplExample.ExecuteWriter(pongo2.Context{"query": r.FormValue("query")}, w)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }
}

func main() {
    http.HandleFunc("/", examplePage)
    http.ListenAndServe(":8080", nil)
}
```

pongo2

Fast, powerful, yet easy to use template engine. Converts templates into Go code and then compiles it

quicktemplate

# gorazor

[![Go Report Card](https://goreportcard.com/badge/github.com/sipin/gorazor?v=1)](https://goreportcard.com/report/github.com/sipin/gorazor)
<a href='https://github.com/jpoles1/gopherbadger' target='_blank'>![gopherbadger-tag-do-not-edit](https://img.shields.io/badge/Go%20Coverage-90%25-brightgreen.svg?longCache=true&style=flat)</a>
[![996.icu](https://img.shields.io/badge/link-996.icu-red.svg)](https://996.icu)
[![LICENSE](https://img.shields.io/badge/license-Anti%20996-blue.svg)](https://github.com/996icu/996.ICU/blob/master/LICENSE)

`gorazor` is the Go port of the razor view engine originated from [asp.net in 2011](http://weblogs.asp.net/scottgu/archive/2010/07/02/introducing-razor.aspx). In summary, `gorazor` is:

* Extremely Fast. Templates are converted into Go code and then compiled with optimizations.
* Concise syntax, no delimiter like `<?`, `<%`, or `{{`.
  * Original [Razor Syntax](http://www.asp.net/web-pages/tutorials/basics/2-introduction-to-asp-net-web-programming-using-the-razor-syntax) & [quick reference](http://haacked.com/archive/2011/01/06/razor-syntax-quick-reference.aspx/) for asp.net.
* Able to mix go code in view template
  * Insert code block to import & call arbitrary go modules & functions
  * Flow controls are just Go, no need to learn another mini-language
* Code generation approach
  * No reflection overhead
  * Go compiler validation for free
* Strong type view model
* Embedding templates support
* Layout/Section support

# Extremely Fast

`gorazor` is about **20X** times faster than [html/template](https://golang.org/pkg/html/template/) when using standard `strings.Builder` for template writing.

When using `quicktemplate`'s `ByteBuffer` and `unsafeStrToBytes` method to for template writing, `gorazor`'s performance is comparable to [quicktemplate](https://github.com/valyala/quicktemplate), if not faster.

Benchmark results:
```bash
$ go test -bench='Benchmark(Razor|RazorQuick|Quick|HTML)Template' -benchmem github.com/valyala/quicktemplate/tests github.com/sipin/gorazor/tests
goos: windows
goarch: amd64
pkg: github.com/valyala/quicktemplate/tests
BenchmarkQuickTemplate1-8       50000000                35.6 ns/op             0 B/op          0 allocs/op
BenchmarkQuickTemplate10-8      10000000               152 ns/op               0 B/op          0 allocs/op
BenchmarkQuickTemplate100-8      1000000              1460 ns/op               0 B/op          0 allocs/op
BenchmarkHTMLTemplate1-8         2000000               712 ns/op             608 B/op         21 allocs/op
BenchmarkHTMLTemplate10-8         500000              3586 ns/op            2834 B/op        111 allocs/op
BenchmarkHTMLTemplate100-8         50000             35180 ns/op           28055 B/op       1146 allocs/op
PASS
ok      github.com/valyala/quicktemplate/tests  11.360s
goos: windows
goarch: amd64
pkg: github.com/sipin/gorazor/tests
BenchmarkRazorTemplate1-8                       30000000                49.8 ns/op           224 B/op          3 allocs/op
BenchmarkRazorTemplate10-8                      10000000               122 ns/op             480 B/op          4 allocs/op
BenchmarkRazorTemplate100-8                      2000000               931 ns/op            4064 B/op          7 allocs/op
BenchmarkRazorQuickTemplate1-8                  100000000               19.9 ns/op             0 B/op          0 allocs/op
BenchmarkRazorQuickTemplate10-8                 20000000                82.5 ns/op             0 B/op          0 allocs/op
BenchmarkRazorQuickTemplate100-8                 2000000               767 ns/op               0 B/op          0 allocs/op
BenchmarkRazorQuickTemplateOriginal1-8          100000000               17.4 ns/op             0 B/op          0 allocs/op
BenchmarkRazorQuickTemplateOriginal10-8         20000000                68.8 ns/op             0 B/op          0 allocs/op
BenchmarkRazorQuickTemplateOriginal100-8         2000000               656 ns/op               0 B/op          0 allocs/op
PASS
ok      github.com/sipin/gorazor/tests  19.921s
```

* `BenchmarkRazorQuickTemplate`'s manually modified ensure **exact output** as quicktemplate for comparism.
* `BenchmarkRazorQuickTemplateOriginal` are `gorazor`'s default code-gen, which produce less white-space, thus faster.

# Usage

`gorazor` supports `go 1.10` and above, for go version **below 1.10**, you may use [gorazor classic version](https://github.com/sipin/gorazor/releases/tag/v1.0).

`go 1.12` and above are recommended for better **compiler optimization**.

## Install

```sh
go install github.com/sipin/gorazor@latest
```

## Usage

* Process folder: `gorazor template_folder output_folder`
* Process file: `gorazor template_file output_file`

## Examples

[Examples] gives examples using layout / helper etc.

When using layout, you may need to set `-prefix` parameter, like:

```bash
git clone https://github.com/sipin/gorazor/
cd gorazor
go build

# -prefix parameter here tells gorazor the current folder is the base path for github.com/sipin/gorazor
# So that, when importing "github.com/sipin/gorazor/examples/tpl/layout" in example/tpl/home.gohtml
# gorazor will know how to find the layout/helper files
./gorazor -prefix github.com/sipin/gorazor ./examples/tpl ./examples/tpl
go run example/main.go
```

# Syntax

## Variable

* `@variable` to insert **string** variable into html template
  * variable could be wrapped by arbitrary go functions
  * variable inserted will be automatically [escaped](http://golang.org/pkg/html/template/#HTMLEscapeString)

```html
<div>Hello @user.Name</div>
```

```html
<div>Hello @strings.ToUpper(req.CurrentUser.Name)</div>
```

Use `raw` to skip escaping:

```html
<div>@raw(user.Name)</div>
```

Only use `raw` when you are 100% sure what you are doing, please always be aware of [XSS attack](http://en.wikipedia.org/wiki/Cross-site_scripting).

## Flow Control

```php
@if .... {
	....
}

@if .... {
	....
} else {
	....
}

@for .... {

}

@{
	switch .... {
	case ....:
	      <p>...</p>
	case 2:
	      <p>...</p>
	default:
	      <p>...</p>
	}
}
```

Please use [example](https://github.com/sipin/gorazor/blob/master/examples/tpl/home.gohtml) for reference.

## Code block

Arbitrary go code could be used in templates, like creating a new variable.

```html
@{
	username := u.Name
	if u.Email != "" {
		username += "(" + u.Email + ")"
	}
}
<div class="welcome">
<h4>Hello @username</h4>
</div>
```

It's recommended to keep clean separation of code & view. **Please consider** move logic into your code before creating a code block in a template.

## Declaration

The **first code block** in template is strictly for declaration:

* imports
* model type
* layout

like:

```go
@{
	import  (
		"kp/models"   //import `"kp/models"` package
		"tpl/layout"  //import tpl/layout namespace
	)

	layout := layout.Base //Use layout package's **Base func** for layout
	var user *models.User //1st template param
	var blog *models.Blog //2nd template param
}
...
```

**first code block** must be at the beginning of the template, i.e. before any html.

Any other codes inside the first code block will **be ignored**.

import must be wrapped in `()`, `import "package_name"` is not yet supported.

The variables declared in **first code block** will be the models of the template, i.e. the parameters of generated function.

If your template doesn't need any model input, then just leave it blank.

## Helper / Include other template

As `gorazor` compiles templates to go function, embedding another template is just calling the generated function, like any other go function.

However, if the templates are designed to be embedded, they must be under `helper` namespace, i.e. put them in `helper` sub-folder.

So, using a helper template is similar to:

```html

@if msg != "" {
	<div>@helper.ShowMsg(msg)</div>
}

```

`gorazor` won't HTML escape the output of `helper.XXX`.

Please use [example](https://github.com/sipin/gorazor/blob/master/examples/tpl/home.gohtml) for reference.

## Layout & Section

The syntax for declaring layout is a bit tricky, in the example mentioned above:

```go
@{
	import  (
		"tpl/layout"
	)

	layout := layout.Base //Use layout package's **base func** for layout
}
```

`"tpl/layout"` **is** the layout package namespace, and the `layout` variable refers to `"layout.Base"` func, which should be generated by `tpl/layout/base.gohtml`.

> Must use `layout` as the variable name

### Package / Variable convention

* The namespace/folder name for layout templates **must be** `layout`
  * `gorazor` relies on this to determine if a template is for layout
* The template `variable name` also **must be** `layout`

A layout file `tpl/layout/base.gohtml` may look like:

```html
@{
	var body string
	var sidebar string
	var footer string
	var title string
	var css string
	var js string
}

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8" />
	<title>@title</title>
</head>
<body>
    <div class="container">@body</div>
    <div class="sidebar">@sidebar</div>
    <div class="footer">@footer</div>
	@js
  </body>
</html>
```

It's just a usual `gorazor` template, but:

* First param must be `var body string` (As it's always required, maybe we could remove it in future?)
* All params **must be** string, each param is considered as a **section**, the variable name is the **section name**.
* Under `layout` package, i.e. within "layout" folder.
  * Optionally, use `isLayout := true` to declare a template as layout

A template using such layout `tpl/index.gohtml` may look like:

```html
@{
	import (
		"tpl/layout"
	)

	layout := layout.Base
}

@section footer {
	<div>Copyright 2014</div>
}

<h2>Welcome to homepage</h2>
```

It's also possible to use import alias:

```html
@{
	import (
		share "tpl/layout"
	)

	layout := share.Base
}
```

With the page, the page content will be treated as the `body` section in the layout.

The other section content need to be wrapped with
```
@section SectionName {
	....
}
```

The template doesn't need to specify all sections defined in the layout. If a section is not specified, it will be considered as `""`.

Thus, it's possible for the layout to define default section content in such manner:

```html
@{
	var body string
	var sidebar string
}

<body>
    <div class="container">@body</div>
    @if sidebar == "" {
    <div class="sidebar">I'm the default side bar</div>
	} else {
    <div class="sidebar">@sidebar</div>
	}
</body>
```

* A layout should be able to use another layout, it's just function call.

# Conventions

* Template **folder name** will be used as **package name** in generated code
* Template file name must has the extension name `.gohtml`
* Template strip of `.gohtml` extension name will be used as the **function name** in generated code, with **first letter Capitalized**.
  * So that the function will be accessible to other modules. (I hate GO about this.)
* Helper templates **must** has the package name **helper**, i.e. in `helper` folder.
* Layout templates **must** has the package name **layout**, i.e. in `layout` folder.

# Example

Here is a simple example of [gorazor templates](https://github.com/sipin/gorazor/tree/master/examples/tpl) and the corresponding [generated codes](https://github.com/sipin/gorazor/tree/master/examples/gen).

# FAQ

## IDE / Editor support?

### Sublime Text 2/3

* **Syntax highlight** Search & install `gorazor` via Package Control.
* **Context aware auto-completion**, you may need to [manually modify](https://github.com/sipin/GoSublime/commit/fd0b979e7cc1d8f2438bb314399c2456d16f3ffb) GoSublime package, basically replace `gscomplete.py` in with [this](https://raw.githubusercontent.com/sipin/GoSublime/gorazor/gscomplete.py) and `gslint.py` with [this](https://raw.githubusercontent.com/sipin/GoSublime/gorazor/gslint.py)

### Emacs
[web-mode](http://web-mode.org/) supports Razor template engine, so add this into your Emacs config file:

```lisp
(require 'web-mode)
(add-hook 'web-mode-hook  'my-web-mode-hook)
(add-to-list 'auto-mode-alist '("\\.html?\\'" . web-mode))
(add-to-list 'auto-mode-alist '("\\.gohtml\\'" . web-mode))
(add-to-list 'auto-mode-alist '("\\.js\\'" . web-mode))
(setq web-mode-engines-alist '(("razor" . "\\.gohtml\\'")))
```

# Credits

The very [first version](https://github.com/sipin/gorazor/releases/tag/vash) of `gorazor` is a hack of razor's port in javascript: [vash](https://github.com/kirbysayshi/vash), thus requires node's to run.

`gorazor` has been though several rounds of refactoring, and it has completely rewritten in pure Go. Nonetheless, THANK YOU [@kirbysayshi](https://github.com/kirbysayshi) for Vash! Without Vash, `gorazor` may never start.

# LICENSE

[LICENSE](LICENSE)? Well, [WTFPL](http://www.wtfpl.net/about/) and [996.icu](LICENSE).

# Project Status

Feature completed.

Archived [todo](https://github.com/sipin/gorazor/blob/master/todo.md)


Razor

Closure templates (aka Soy templates) for Go, following the [official spec](https://developers.google.com/closure/templates/)

# soy

[![GoDoc](http://godoc.org/github.com/robfig/soy?status.png)](http://godoc.org/github.com/robfig/soy)
[![Build Status](https://github.com/robfig/soy/actions/workflows/go.yaml/badge.svg?query=branch%3Amaster)](https://github.com/robfig/soy/actions/workflows/go.yaml?query=branch%3Amaster)
[![Go Report Card](https://goreportcard.com/badge/robfig/soy)](https://goreportcard.com/report/robfig/soy)

Go implementation for Soy templates aka [Google Closure
Templates](https://github.com/google/closure-templates).  See
[godoc](http://godoc.org/github.com/robfig/soy) for more details and usage
examples.

This project requires Go 1.12 or higher due to one of the transitive
dependencies requires it as a minimum version; otherwise, Go 1.11 would
suffice for `go mod` support.

Be sure to set the env var `GO111MODULE=on` to use the `go mod` dependency
versioning when building and testing this project.


A really simple way to create text templates with placeholders - exposes extra builtin Git repo metadata

# `tbd`

[![Go Report Card](https://goreportcard.com/badge/github.com/lucasepe/tbd?style=flat-square)](https://goreportcard.com/report/github.com/lucasepe/tbd) &nbsp;&nbsp;&nbsp;
[![Release](https://img.shields.io/github/release/lucasepe/tbd.svg?style=flat-square)](https://github.com/lucasepe/tbd/releases/latest) &nbsp;&nbsp;&nbsp;
[![codecov](https://codecov.io/gh/lucasepe/tbd/branch/main/graph/badge.svg?style=flat-square)](https://codecov.io/gh/lucasepe/tbd)

_"to be defined"_

## A really simple way to create text templates with placeholders.

This tool is deliberately simple and trivial, no advanced features. 

> If you need advanced templates rendering which supports complex syntax and a huge list of datasources (JSON, YAML,  AWS EC2 metadata, BoltDB, Hashicorp > Consul and Hashicorp Vault secrets), I recommend you use one of these:
>
> - [gotemplate](https://github.com/hairyhenderson/gomplate)
> - [pongo2](https://github.com/flosch/pongo2)
> - [quicktemplate](https://github.com/valyala/quicktemplate)

## Built-in Variables

When executed inside a Git repository, `tbd` automatically exports some variables related to the Git repository which may be useful in the build phase.

These variables are: `ARCH`, `OS`, `REPO_COMMIT`, `REPO_HOST`, `REPO_NAME`, `REPO_ROOT`, `REPO_TAG`, `REPO_TAG_CLEAN`, `REPO_URL`, `TIMESTAMP`.

Try it! With `tbd` in your `PATH`, go in a Git folder and type:

```sh
$ tbd vars
+----------------+------------------------------------------+
| ARCH           | amd64                                    |
| OS             | linux                                    |
| REPO_COMMIT    | a3193274112d3a6f5c2a0277e2ca07ec238d622f |
| REPO_HOST      | github.com                               |
| REPO_NAME      | tbd                                      |
| REPO_ROOT      | lucasepe                                 |
| REPO_TAG       | v0.1.1                                   |
| REPO_TAG_CLEAN | 0.1.1                                    |
| REPO_URL       | https://github.com/lucasepe/tbd          |
| TIMESTAMP      | 2021-07-26T14:22:36Z                     |
+----------------+------------------------------------------+
```

> Obviously in your case the values ​​will be different.

## How does a template looks like ?

A template is a text document in which you can insert placeholders for the text you want to make dynamic.

- a placeholder is delimited by `{{` and `}}` - (i.e. `{{ FULL_NAME }}`)
- all text outside placeholders is copied to the output unchanged

Example:

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: {{ metadata.name }}
  labels:
    app: {{ metadata.labels.app }}
 spec:
  containers:
    - name: {{ container.1.name }}
      image: {{ container.1.image }}
      ports:
        - containerPort: {{ container.1.port }}
    - name: {{ container.2.name }}
      image: {{ container.2.image }}
      ports:
        - containerPort: {{ container.2.port }}
```

Another example:

```txt
{{ greeting }}

I will be out of the office from {{ start.date }} until {{ return.date }}. 
If you need immediate assistance while I’m away, please email {{ contact.email }}.

Best,
{{ name }}
```

## How can I define placeholders values?

Create a text file in which you enter the values for the placeholders.

- define a placeholder value using `KEY = value` (or `KEY: value`)
- empty lines are skipped
- lines beginning with `#` are treated as comments

Example:

```sh
# metadata values
metadata.name = rss-site
metadata.labels.app = web

# containers values
container.1.name = front-end
container.1.image = nginx
container.1.port = 80

container.2.name = rss-reader
container.2.image: nickchase/rss-php-nginx:v1
container.2.port: 88
```

Another example...

```sh
greeting: Greetings
start.date: August, 9 
return.date: August 23
contact.email: pinco.pallo@gmail.com
name: Pinco Pallo 
```

## How fill in the template?

> Use the `merge` command

```sh
$ tbd merge /path/to/your/template /path/to/your/envfile
```

Example:

```sh
$ tbd merge testdata/sample.tbd testdata/sample.vars
```

👉 you can also specify an HTTP url to fetch your template and/or placeholders values.

Example:

```sh
$ tbd merge https://raw.githubusercontent.com/lucasepe/tbd/main/testdata/sample.tbd \
    https://raw.githubusercontent.com/lucasepe/tbd/main/testdata/sample.vars
```

and the output is...

```txt
Greetings

I will be out of the office from August, 9 until August 23. 
If you need immediate assistance while I’m away, please email pinco.pallo@gmail.com.

Best,
Pinco Pallo
```

## How to list all template placeholders?

> Use the `marks` command.

```sh
$ tbd marks /path/to/your/template
```

Example:

```sh
$ tbd marks testdata/sample.tbd
greeting
start.date
return.date
contact.email
name
```

## How to list all variables?

> Use the `vars` command.

```sh
$ tbd vars /path/to/your/envfile
```

Example:

```sh
$ tbd vars testdata/sample.vars
+----------------+------------------------------------------+
| Label          | Value                                    |
+----------------+------------------------------------------+
| ARCH           | amd64                                    |
| OS             | linux                                    |
| REPO_COMMIT    | a3193274112d3a6f5c2a0277e2ca07ec238d622f |
| REPO_HOST      | github.com                               |
| REPO_NAME      | tbd                                      |
| REPO_ROOT      | lucasepe                                 |
| REPO_TAG       | v0.1.1                                   |
| REPO_TAG_CLEAN | 0.1.1                                    |
| REPO_URL       | https://github.com/lucasepe/tbd          |
| TIMESTAMP      | 2021-07-26T14:17:49Z                     |
| contact.email  | pinco.pallo@gmail.com                    |
| greeting       | Greetings                                |
| name           | Pinco Pallo                              |
| return.date    | August 23                                |
| start.date     | August, 9                                |
+----------------+------------------------------------------+
```

> As you can see, since I ran the command in a Git repository, there are also relative variables.

# How to install?

If you have [golang](https://golang.org/dl/) installed:

```sh
$ go install github.com/lucasepe/tbd@latest
```

This will create the executable under your `$GOPATH/bin` directory.

## Ready-To-Use Releases 

If you don't want to compile the sourcecode yourself, [here you can find the tool already compiled](https://github.com/lucasepe/tbd/releases/latest) for:

- MacOS
- Linux
- Windows

<br/>

#### Credits

Thanks to [@valyala](https://github.com/valyala/) for the [fasttemplate](https://github.com/valyala/fasttemplate) library - which I have modified by adding and removing some functions for the `tbd` purpose.


A HTML templating language that has great developer tooling

![templ](https://github.com/a-h/templ/raw/main/templ.png)

## An HTML templating language for Go that has great developer tooling.

![templ](ide-demo.gif)


## Documentation

See user documentation at https://templ.guide

<p align="center">
<a href="https://pkg.go.dev/github.com/a-h/templ"><img src="https://pkg.go.dev/badge/github.com/a-h/templ.svg" alt="Go Reference" /></a>
<a href="https://xcfile.dev"><img src="https://xcfile.dev/badge.svg" alt="xc compatible" /></a>
<a href="https://raw.githack.com/wiki/a-h/templ/coverage.html"><img src="https://github.com/a-h/templ/wiki/coverage.svg" alt="Go Coverage" /></a>
<a href="https://goreportcard.com/report/github.com/a-h/templ"><img src="https://goreportcard.com/badge/github.com/a-h/templ" alt="Go Report Card" /></a>
</p>

## Tasks

### version-set

Set the version of templ to the current version.

```sh
version set --template="0.3.%d"
```

### build

Build a local version.

```sh
version set --template="0.3.%d"
cd cmd/templ
go build
```

### install-snapshot

Build and install current version.

```sh
# Remove templ from the non-standard ~/bin/templ path
# that this command previously used.
rm -f ~/bin/templ
# Clear LSP logs.
rm -f cmd/templ/lspcmd/*.txt
# Update version.
version set --template="0.3.%d"
# Install to $GOPATH/bin or $HOME/go/bin
cd cmd/templ && go install
```

### build-snapshot

Use goreleaser to build the command line binary using goreleaser.

```sh
goreleaser build --snapshot --clean
```

### generate

Run templ generate using local version.

```sh
go run ./cmd/templ generate -include-version=false
```

### test

Run Go tests.

```sh
version set --template="0.3.%d"
go run ./cmd/templ generate -include-version=false
go test ./...
```

### test-short

Run Go tests.

```sh
version set --template="0.3.%d"
go run ./cmd/templ generate -include-version=false
go test ./... -short
```

### test-cover

Run Go tests.

```sh
# Create test profile directories.
mkdir -p coverage/fmt
mkdir -p coverage/generate
mkdir -p coverage/version
mkdir -p coverage/unit
# Build the test binary.
go build -cover -o ./coverage/templ-cover ./cmd/templ
# Run the covered generate command.
GOCOVERDIR=coverage/fmt ./coverage/templ-cover fmt .
GOCOVERDIR=coverage/generate ./coverage/templ-cover generate -include-version=false
GOCOVERDIR=coverage/version ./coverage/templ-cover version
# Run the unit tests.
go test -cover ./... -coverpkg ./... -args -test.gocoverdir="$PWD/coverage/unit"
# Display the combined percentage.
go tool covdata percent -i=./coverage/fmt,./coverage/generate,./coverage/version,./coverage/unit
# Generate a text coverage profile for tooling to use.
go tool covdata textfmt -i=./coverage/fmt,./coverage/generate,./coverage/version,./coverage/unit -o coverage.out
# Print total
go tool cover -func coverage.out | grep total
```

### test-cover-watch

interactive: true

```sh
gotestsum --watch -- -coverprofile=coverage.out
```

### test-fuzz

```sh
./parser/v2/fuzz.sh
./parser/v2/goexpression/fuzz.sh
```

### benchmark

Run benchmarks.

```sh
go run ./cmd/templ generate -include-version=false && go test ./... -bench=. -benchmem
```

### fmt

Format all Go and templ code.

```sh
gofmt -s -w .
go run ./cmd/templ fmt .
```

### lint

Run the lint operations that are run as part of the CI.

```sh
golangci-lint run --verbose
```

### ensure-generated

Ensure that templ files have been generated with the local version of templ, and that those files have been added to git.

Requires: generate

```sh
git diff --exit-code
```

### push-release-tag

Push a semantic version number to GitHub to trigger the release process.

```sh
version push --template="0.3.%d" --prefix="v"
```

### docs-run

Run the development server.

Directory: docs

```sh
npm run start
```

### docs-build

Build production docs site.

Directory: docs

```sh
npm run build
```



templ

A type-safe HTML template rendering engine for Go

# Templator

[![codecov](https://codecov.io/gh/alesr/templator/graph/badge.svg?token=HiYBMXeIbg)](https://codecov.io/gh/alesr/templator)
[![Go Report Card](https://goreportcard.com/badge/github.com/alesr/templator)](https://goreportcard.com/report/github.com/alesr/templator)
[![Go Reference](https://pkg.go.dev/badge/github.com/alesr/templator.svg)](https://pkg.go.dev/github.com/alesr/templator)
[![Go Version](https://img.shields.io/badge/Go-%3E%3D1.24-00ADD8?logo=go&logoColor=white)](https://go.dev/)
[![License: MIT](https://img.shields.io/github/license/alesr/templator?color=blue)](https://github.com/alesr/templator/blob/main/LICENSE)
[![Latest Release](https://img.shields.io/github/v/release/alesr/templator)](https://github.com/alesr/templator/releases/latest)

A type-safe HTML template rendering engine for Go.

## Table of Contents

- [Problem Statement](#problem-statement)
- [What Templator Solves](#what-templator-solves)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [How It All Works Together](#how-it-all-works-together)
- [Usage Examples](#usage-examples)
- [Template Generation](#template-generation)
- [Configuration](#configuration)
- [Development Requirements](#development-requirements)
- [Contributing](#contributing)
- [License](#license)

## Problem Statement

Go's built-in `html/template` package is great, but it has one big weakness: no type safety.

```go
tmpl := template.Must(template.ParseFiles("home.html"))

// this compiles fine...
err := tmpl.Execute(w, struct {
    WrongField   string
    MissingStuff int
}{})
```

You only find out at runtime that your data does not match what the template expects: missing fields, typos, wrong types, and so on.

## What Templator Solves

Templator wraps `html/template` and gives you compile-time guarantees with generics.

You define your data once:

```go
type HomeData struct {
    Title   string
    Content string
}
```

Then template execution is type-checked against the template by the compiler.

You can get a handler in two equivalent ways:

1. Simple and direct: `reg.Get("home")`
2. IDE-friendly codegen: `tpl.GetHome()`

Both return `*Handler[T]` with the same behavior. The difference is only developer experience.

## Features

- Compile-time type safety via generics
- Optional field validation (catches mismatches when loading templates)
- Concurrent-safe template management with `fs.FS` support
- Custom template functions
- Context cancellation and deadline propagation
- Minimal overhead on top of `html/template`
- Small API with optional code generation helpers

## Installation

```bash
go get github.com/alesr/templator@latest
```

Optional generator binary:

```bash
go install github.com/alesr/templator/cmd/generate@latest
```

## Quick Start

```go
package main

import (
    "context"
    "log"
    "os"

    "github.com/alesr/templator"
)

type HomeData struct {
    Title   string
    Content string
}

func main() {
    fs := os.DirFS(".")

    reg, err := templator.NewRegistry[HomeData](fs)
    if err != nil {
        log.Fatal(err)
    }

    home, err := reg.Get("home")
    if err != nil {
        log.Fatal(err)
    }

    err = home.Execute(context.Background(), os.Stdout, HomeData{
        Title:   "Welcome",
        Content: "Hello, World!",
    })
    if err != nil {
        log.Fatal(err)
    }
}
```

## How It All Works Together

1. Define a data struct (this is your type parameter `T`).
2. Create a `Registry[T]` for your filesystem.
3. Get a `Handler[T]` either with `reg.Get("name")` or generated accessors like `tpl.GetName()`.
4. Execute with `handler.Execute(ctx, writer, data)`.
5. Optionally enable field validation, custom functions, or a different templates path.

Everything is still powered by the standard `html/template` package.

## Usage Examples

### Type-Safe Templates (different data per template)

```go
type HomeData struct{ Title, Content string }
type AboutData struct{ Company string; Year int }

homeReg, _ := templator.NewRegistry[HomeData](fs)
aboutReg, _ := templator.NewRegistry[AboutData](fs)

home, _ := homeReg.Get("home")
about, _ := aboutReg.Get("about")

home.Execute(ctx, w, HomeData{...})  // ok
home.Execute(ctx, w, AboutData{...}) // trying to pass about data to the home tmpl is caught by the compiler
```

### Custom Template Functions

```go
funcMap := template.FuncMap{
    "upper": strings.ToUpper,
}

reg, _ := templator.NewRegistry[PageData](
    fs,
    templator.WithTemplateFuncs[PageData](funcMap),
)
```

Use in templates as usual: `{{.Title | upper}}`

### File System Support

```go
// Embedded FS
//go:embed templates/*
var embedFS embed.FS

reg, _ := templator.NewRegistry[HomeData](embedFS)

// os dir
reg, _ = templator.NewRegistry[HomeData](os.DirFS("templates"))

// in-memory for tests
fsys := fstest.MapFS{ /* ... */ }
reg, _ = templator.NewRegistry[HomeData](fsys)
```

### Field Validation (catches errors early)

```go
type ArticleData struct {
    Title   string
    Content string
}

reg, _ := templator.NewRegistry[ArticleData](
    fs,
    templator.WithFieldValidation(ArticleData{}),
)
```

If a template references `{{.Author}}` but `Author` does not exist in `ArticleData`, `Get(...)` returns a validation error.

## Template Generation

Want `tpl.GetHome()` instead of string lookup? Use the generator.

```bash
go run github.com/alesr/templator/cmd/generate \
  -package main \
  -templates ./templates \
  -out ./templator_accessors_gen.go
```

You can also wire it into `go generate`:

```go
//go:generate go run github.com/alesr/templator/cmd/generate -package main -templates ./templates -out ./templator_accessors_gen.go
```

Then use the generated wrapper:

```go
reg, _ := templator.NewRegistry[HomeData](fs)
tpl := NewTemplateAccessors(reg)

home, _ := tpl.GetHome()
header, _ := tpl.GetComponentsHeader()
```

`components/header.html` maps to `GetComponentsHeader`.

For full generator docs (flags, behavior, and examples), see [`cmd/generate/README.md`](cmd/generate/README.md).

## Configuration

```go
reg, err := templator.NewRegistry[HomeData](
    fs,
    templator.WithTemplatesPath[HomeData]("views"),
    templator.WithTemplateFuncs[HomeData](funcMap),
    templator.WithFieldValidation(HomeData{}),
)
```

## Development Requirements

- Go 1.24 or higher

## Contributing

Contributions are welcome.

## License

MIT


templator

Lightweight templating language that lets you write templates in Go. Templates are translated into Go and compiled

Ego [![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=flat-square)](https://godoc.org/github.com/benbjohnson/ego)
===

Ego is an [ERb](http://ruby-doc.org/stdlib-2.1.0/libdoc/erb/rdoc/ERB.html) style templating language for Go. It works by transpiling templates into pure Go and including them at compile time. These templates are light wrappers around the Go language itself.

## Install

You can find a release build of ego for Linux on the [Releases page](https://github.com/benbjohnson/ego/releases).

To install ego from source, you can run this command outside of the `GOPATH`:

```sh
$ go get github.com/benbjohnson/ego/...
```


## Usage

Run `ego` on a directory. Recursively traverse the directory structure and generate Go files for all matching `.ego` files.

```sh
$ ego mypkg
```


## How to Write Templates

An ego template lets you write text that you want to print out but gives you some handy tags to let you inject actual Go code.
This means you don't need to learn a new scripting language to write ego templates—you already know Go!

### Raw Text

Any text the `ego` tool encounters that is not wrapped in `<%` and `%>` tags is considered raw text.
If you have a template like this:

```
hello!
goodbye!
```

Then `ego` will generate a matching `.ego.go` file:

```
io.WriteString(w, "hello!\ngoodbye!")
```

Unfortunately that file won't run because we're missing a `package` line at the top.
We can fix that with _code blocks_.


### Code Blocks

A code block is a section of your template wrapped in `<%` and `%>` tags.
It is raw Go code that will be inserted into our generate `.ego.go` file as-is.

For example, given this template:

```
<%
package myapp

func Render(ctx context.Context, w io.Writer) {
%>
hello!
goodbye!
<% } %>
```

The `ego` tool will generate:

```
package myapp

import (
	"context"
	"io"
)

func Render(ctx context.Context, w io.Writer) {
	io.WriteString(w, "hello!\ngoodbye!")
}
```

_Note the `context` and `io` packages are automatically imported to your template._
_These are the only packages that do this._
_You'll need to import any other packages you use._


### Print Blocks

Our template is getting more useful.
We now have actually runnable Go code.
However, our templates typically need output text frequently so there are blocks specifically for this task called _print blocks_.
These print blocks wrap a Go expression with `<%=` and `%>` tags.

We can expand our previous example and add a type and fields to our code:


```
<%
package myapp

type NameRenderer struct {
	Name  string
	Greet bool
}

func (r *NameRenderer) Render(ctx context.Context, w io.Writer) {
%>
	<% if r.Greet { %>
		hello, <%= r.Name %>!
	<% } else { %>
		goodbye, <%= r.Name %>!
	<% } %>
<% } %>
```

We now have a conditional around our `Greet` field and we are printing the `Name` field.
Our generated code will look like:


```
package myapp

import (
	"context"
	"io"
)

type NameRenderer struct {
	Name  string
	Greet bool
}

func Render(ctx context.Context, w io.Writer) {
	if r.Greet {
		io.WriteString(w, "hello, ")
		io.WriteString(w, html.EscapeString(fmt.Sprint(r.Name)))
		io.WriteString(w, "!")
	} else {
		io.WriteString(w, "goodbye, ")
		io.WriteString(w, html.EscapeString(fmt.Sprint(r.Name)))
		io.WriteString(w, "!")
	}
}
```


#### Printing unescaped HTML

The `<%= %>` block will print your text as escaped HTML, however, sometimes you need the raw text such as when you're writing JSON.
To do this, simply wrap your Go expression with `<%==` and `%>` tags.


### Components

Simple code and print tags work well for simple templates but it can be difficult to make reusable functionality.
You can use the component syntax to print types that implement this `Renderer` interface:

```
type Renderer interface {
	Render(context.Context, io.Writer)
}
```

Component syntax look likes HTML.
You specify the type you want to instantiate as the node name and then use attributes to assign values to fields.
The body of your component will be assigned as a closure to a field called `Yield` on your component type.

For example, let's say you want to make a reusable button that outputs [Bootstrap 4.0](http://getbootstrap.com/) code:
We can write this component as an ego template or in pure Go code.
Here we'll write the component in Go:

```
package myapp

import (
	"context"
	"io"
)

type Button struct {
	Style string
	Yield func()
}

func (r *Button) Render(ctx context.Context, w io.Writer) {
	fmt.Fprintf(w, `<div class="btn btn-%s">`, r.Style)
	if r.Yield {
		r.Yield()
	}
	fmt.Fprintf(w, `</div>`)
}
```

Now we can use that component from a template in the same package like this:

```
<%
package myapp

type MyTemplate struct {}

func (r *MyTemplate) Render(ctx context.Context, w io.Writer) {
%>
	<div class="container">
		<ego:Button Style="danger">Don't click me!</ego:Button>
	</div>
<% } %>
```

Our template automatically convert our component syntax into an instance and invocation of `Button`:

```
var EGO Button
EGO.Style = "danger"
EGO.Yield = func() { io.WriteString(w, "Don't click me!") }
EGO.Render(ctx, w)
```

Field values can be specified as any Go expression.
For example, you could specify a function to return a value for `Button.Style`:

```
<ego:Button Style=r.ButtonStyle()>Don't click me!</ego:Button>
```

#### Named closures

The `Yield` is a special instance of a closure, however, you can also specify named closures using the `::` syntax.

Given a component type:

```
type MyView struct {
	Header func()
	Yield  func()
}
```

We can specify the separate closures like this:

```
<ego:MyView>
	<ego::Header>
		This content will go in the Header closure.
	</ego::Header>

	This content will go in the Yield closure.
</ego:MyView>
```

#### Importing components from other packages

You can import components from other packages by using a namespace that matches the package name
The `ego` namespace is reserved to import types in the current package.

For example, you can import components from a library such as [bootstrap-ego](https://github.com/benbjohnson/bootstrap-ego):

```
<%
package myapp

import "github.com/benbjohnson/bootstrap-ego"

type MyTemplate struct {}

func (r *MyTemplate) Render(ctx context.Context, w io.Writer) {
%>
	<bootstrap:Container>
		<bootstrap:Row>
			<div class="col-md-3">
				<bootstrap:Button Style="danger" Size="lg">Don't click me!</bootstrap:Button>
			</div>
		</bootstrap:Row>
	</bootstrap:Container>
<% } %>
```


## Caveats

Unlike other runtime-based templating languages, ego does not support ad hoc templates. All templates must be generated before compile time.

Ego does not attempt to provide any security around the templates. Just like regular Go code, the security model is up to you.


Simple and fast template engine. Substitutes template placeholders up to 10x faster than [text/template](https://golang.org/pkg/text/template/)

fasttemplate
============

Simple and fast template engine for Go.

Fasttemplate performs only a single task - it substitutes template placeholders
with user-defined values. At high speed :)

Take a look at [quicktemplate](https://github.com/valyala/quicktemplate) if you  need fast yet powerful html template engine.

*Please note that fasttemplate doesn't do any escaping on template values
unlike [html/template](http://golang.org/pkg/html/template/) do. So values
must be properly escaped before passing them to fasttemplate.*

Fasttemplate is faster than [text/template](http://golang.org/pkg/text/template/),
[strings.Replace](http://golang.org/pkg/strings/#Replace),
[strings.Replacer](http://golang.org/pkg/strings/#Replacer)
and [fmt.Fprintf](https://golang.org/pkg/fmt/#Fprintf) on placeholders' substitution.

Below are benchmark results comparing fasttemplate performance to text/template,
strings.Replace, strings.Replacer and fmt.Fprintf:

```
$ go test -bench=. -benchmem
PASS
BenchmarkFmtFprintf-4                   	 2000000	       790 ns/op	       0 B/op	       0 allocs/op
BenchmarkStringsReplace-4               	  500000	      3474 ns/op	    2112 B/op	      14 allocs/op
BenchmarkStringsReplacer-4              	  500000	      2657 ns/op	    2256 B/op	      23 allocs/op
BenchmarkTextTemplate-4                 	  500000	      3333 ns/op	     336 B/op	      19 allocs/op
BenchmarkFastTemplateExecuteFunc-4      	 5000000	       349 ns/op	       0 B/op	       0 allocs/op
BenchmarkFastTemplateExecute-4          	 3000000	       383 ns/op	       0 B/op	       0 allocs/op
BenchmarkFastTemplateExecuteFuncString-4	 3000000	       549 ns/op	     144 B/op	       1 allocs/op
BenchmarkFastTemplateExecuteString-4    	 3000000	       572 ns/op	     144 B/op	       1 allocs/op
BenchmarkFastTemplateExecuteTagFunc-4   	 2000000	       743 ns/op	     144 B/op	       3 allocs/op
```


Docs
====

See http://godoc.org/github.com/valyala/fasttemplate .


Usage
=====

```go
	template := "http://{{host}}/?q={{query}}&foo={{bar}}{{bar}}"
	t := fasttemplate.New(template, "{{", "}}")
	s := t.ExecuteString(map[string]interface{}{
		"host":  "google.com",
		"query": url.QueryEscape("hello=world"),
		"bar":   "foobar",
	})
	fmt.Printf("%s", s)

	// Output:
	// http://google.com/?q=hello%3Dworld&foo=foobarfoobar
```


Advanced usage
==============

```go
	template := "Hello, [user]! You won [prize]!!! [foobar]"
	t, err := fasttemplate.NewTemplate(template, "[", "]")
	if err != nil {
		log.Fatalf("unexpected error when parsing template: %s", err)
	}
	s := t.ExecuteFuncString(func(w io.Writer, tag string) (int, error) {
		switch tag {
		case "user":
			return w.Write([]byte("John"))
		case "prize":
			return w.Write([]byte("$100500"))
		default:
			return w.Write([]byte(fmt.Sprintf("[unknown tag %q]", tag)))
		}
	})
	fmt.Printf("%s", s)

	// Output:
	// Hello, John! You won $100500!!! [unknown tag "foobar"]
```


fasttemplate

# Jet Template Engine for Go

[![Build Status](https://travis-ci.org/CloudyKit/jet.svg?branch=master)](https://travis-ci.org/CloudyKit/jet) [![Build status](https://ci.appveyor.com/api/projects/status/5g4whw3c6518vvku?svg=true)](https://ci.appveyor.com/project/CloudyKit/jet) [![Join the chat at https://gitter.im/CloudyKit/jet](https://badges.gitter.im/CloudyKit/jet.svg)](https://gitter.im/CloudyKit/jet)

Jet is a template engine developed to be easy to use, powerful, dynamic, yet secure and very fast.

* simple and familiar syntax
* supports template inheritance (`extends`) and composition (`block`/`yield`, `import`, `include`)
* descriptive error messages with filename and line number
* auto-escaping
* simple C-like expressions
* very fast execution – Jet can execute templates faster than some pre-compiled template engines
* very light in terms of allocations and memory footprint

## v6

Version 6 brings major improvements to the Go API. Make sure to read through the [breaking changes](./docs/changes.md) before making the jump.

## Docs

- [Go API](https://pkg.go.dev/github.com/CloudyKit/jet/v6#section-documentation)
- [Syntax Reference](./docs/syntax.md)
- [Built-ins](./docs/builtins.md)
- [Wiki](https://github.com/CloudyKit/jet/wiki) (some things are out of date)

## Example application

An example to-do application is available in [examples/todos](./examples/todos). Clone the repository, then (in the repository root) do:
```
  $ cd examples/todos; go run main.go
```

## IntelliJ Plugin

If you use IntelliJ there is a plugin available at https://github.com/jhsx/GoJetPlugin.
There is also a very good Go plugin for IntelliJ – see https://github.com/go-lang-plugin-org/go-lang-idea-plugin.
GoJetPlugin + Go-lang-idea-plugin = happiness!

## Contributing

All contributions are welcome – if you find a bug please report it.

## Contributors

- José Santos (@jhsx)
- Daniel Lohse (@annismckenzie)
- Alexander Willing (@sauerbraten)


The Best Go Libraries For Template Engines (17)