# 📝 Templating and Localization Templates are parsed **once at startup**. The same template engine is used for all output formats. When a custom HTML template is set via `--html-template`, the `--template-name` and `--rotation-mode` flags are ignored. ### Go template primer Error pages uses the standard Go [`text/template`][go-text-template] package (with HTML output treated as text to preserve full control over markup). If you have never written a Go template before, do not worry - it is genuinely one of the **simplest** templating languages around. The full mental model fits in a few minutes. **Key concepts:** - `{{ }}` - action delimiters; everything outside them is emitted verbatim. - `{{ .Field }}` - output a field from the data object (`.` is "current value"). - `{{ if .Cond }} ... {{ else }} ... {{ end }}` - conditional. - `{{ range .Slice }} {{ . }} {{ end }}` - iteration (`.` becomes each element). - `{{ .Value | funcName }}` - pipeline; passes the value on the left as the last argument to the function on the right. - `{{ /* comment */ }}` - comment (not emitted). **Documentation**: - [`text/template` package - the complete, authoritative reference][go-text-template]. - [Go Templates Guide](https://hackmd.io/@gekart/go-templates?utm_source=chatgpt.com) - syntax explained with examples (recommended for beginners). [go-text-template]: https://pkg.go.dev/text/template > [!WARNING] > `{{` and `}}` are reserved as Go template delimiters - any literal occurrence causes a parse error. This is > common in JSDoc type annotations (`/** @param {{ id: number }} ❌ */`), CSS, etc. To work around this, you can simply > add a single space between the braces: `/** @param { { id: number } } ✅ */`. ### Template data All templates receive a data object with the following fields: | Field | Type | Description | |------------------------------|----------|------------------------------------------------------------------------| | `.StatusCode` | `uint16` | HTTP status code (e.g. `404`) | | `.Message` | `string` | Short status text (e.g. `Not Found`) | | `.Description` | `string` | Longer description (e.g. `The server can not find the requested page`) | | `.OriginalURI` | `string` | Request URI that caused the error * | | `.Namespace` | `string` | Kubernetes namespace of the backend service * | | `.IngressName` | `string` | Name of the Ingress resource * | | `.ServiceName` | `string` | Name of the backend service * | | `.ServicePort` | `string` | Port of the backend service * | | `.RequestID` | `string` | Unique request ID * | | `.ForwardedFor` | `string` | Original client IP(s) from `X-Forwarded-For` * | | `.Host` | `string` | Request `Host` header * | | `.HomepageURL` | `string` | Homepage URL set via `--homepage-url` (empty if not configured) | | `.Links` | `[]Link` | Extra links set via `--add-link` (empty slice if not configured) | | `.Config.ShowRequestDetails` | `bool` | Whether `--show-details` is enabled | | `.Config.L10nDisabled` | `bool` | Whether `--disable-l10n` is set | > `*` - Requires `--show-details` Each element of `.Links` has the following sub-fields: | Sub-field | Type | Description | |---------------|----------|-----------------------| | `.Label` | `string` | Link text | | `.URL` | `string` | Target URL | Example usage in a custom template: ```html {{ if .Links }} {{ end }} ``` In addition to the fields above, templates also have access to a set of built-in functions (see below), which are pipeline-friendly (needle before haystack): `{{ .Message | default "Unknown" | upper }}`. | Function | Description | Example | |------------------------------|--------------------------------------------------|----------------------------------------------------------------| | `now` | Current time (`time.Time`) | `{{ now.Format "2006-01-02" }}` / `{{ now.Unix }}` | | `hostname` | Server hostname | `{{ hostname }}` | | `version` | Application version string | `{{ version }}` | | `env "KEY"` | Env var value (sensitive keys masked with `***`) | `{{ env "STAGE" }}` | | `toJson` / `toJSON` | JSON-encode a value | `{{ .Message \| toJson }}` | | `toInt` / `int` | Convert to integer | `{{ .StatusCode \| int }}` | | `toString` / `str` | Convert to string | `{{ .StatusCode \| str }}` | | `escape` | HTML-escape | `{{ .OriginalURI \| escape }}` | | `urlEncode` | URL-encode | `{{ .OriginalURI \| urlEncode }}` | | `trim` | Strip leading/trailing whitespace | `{{ .Message \| trim }}` | | `trimPrefix` | Remove prefix | `{{ .Message \| trimPrefix "Error: " }}` | | `trimSuffix` / `trimPostfix` | Remove suffix | `{{ .Message \| trimSuffix "!" }}` | | `trimAll` | Strip specific characters | `{{ ".test." \| trimAll "." }}` | | `lower` / `upper` | Change case | `{{ .Message \| upper }}` | | `replace` | Replace all occurrences | `{{ .Message \| replace " " "_" }}` | | `contains` | Substring check | `{{ .Message \| contains "test" }}...{{ end }}` | | `hasPrefix` / `hasSuffix` | Prefix/suffix check | `{{ .Message \| hasPrefix "test" }}...{{ end }}` | | `split` | Split string by separator | `{{ split ";" "a;b;c" }}` | | `join` | Join slice with separator | `{{ split ";" "a;b;c" \| join ", " }}` | | `fields` | Split string by whitespace | `{{ fields "foo bar baz" \| join "-" }}` | | `substr` | Substring by rune index and length | `{{ "Hello, World!" \| substr 7 5 }}` | | `truncate` | Truncate with `...` appended | `{{ .Description \| truncate 80 }}` | | `repeat` | Repeat string N times | `{{ "Ha" \| repeat 3 }}` | | `quote` / `squote` | Wrap in double/single quotes | `{{ .Message \| quote }}` | | `count` | Count substring occurrences | `{{ "test" \| count "t" }}` | | `default` | Fallback value for empty input | `{{ .OriginalURI \| default "N/A" }}` | | `coalesce` | First non-empty value from a list | `{{ coalesce .Message .Description "error" }}` | | `ternary` | Inline conditional | `{{ .Config.ShowRequestDetails \| ternary "shown" "hidden" }}` | | `isEmpty` / `isNotEmpty` | Emptiness check | `{{ if isNotEmpty .Description }}...{{ end }}` | | `l10nScript` | Inline the localization JS script | `` | > [!NOTE] > `env` masks values whose key (split by `_`) contains `PASSWORD`, `SECRET`, `KEY`, `TOKEN`, `PASS`, `PWD`, > or `CRED` (case-insensitive). Those calls return a string of `*` characters instead of the actual value. ### Localization HTML pages support automatic **client-side localization** in 15+ languages, templates that want l10n must: 1. Add `data-l10n` attributes to elements whose text content should be translated 2. Include `` in the HTML The browser detects the visitor's preferred language via `navigator.languages` and translates all `[data-l10n]` elements in-place - no server round-trip required. Localization can be disabled globally with `--disable-l10n` (or via env `DISABLE_L10N=true`). You can find more details on handling localization in templates in the [Localization documentation](../l10n/readme.md).