CustomFunctions is the interface for registering custom template functions.

Field name	Field type	Comment
type	any	No comment on field.

TemplateContext is the TemplateContext with which HTTP templates are executed.

Field name	Field type	Comment
Root	http.FileSystem	No comment on field.
Req	*http.Request	No comment on field.
Args	[]any	No comment on field.
RespHeader	WrappedHeader	No comment on field.
CustomFuncs	[]template.FuncMap	No comment on field.
config	*Templates	No comment on field.
tpl	*template.Template	No comment on field.

Templates is a middleware which executes response bodies as Go templates. The syntax is documented in the Go standard library's text/template package.

⚠️ Template functions/actions are still experimental, so they are subject to change.

Custom template functions can be registered by creating a plugin module under the http.handlers.templates.functions.* namespace that implements the CustomFunctions interface.

All Sprig functions are supported.

In addition to the standard functions and the Sprig library, Caddy adds extra functions and data that are available to a template:

.Args

A slice of arguments passed to this page/context, for example as the result of a include.

{{index .Args 0}} // first argument

.Cookie

Gets the value of a cookie by name.

{{.Cookie "cookiename"}}

env

Gets an environment variable.

{{env "VAR_NAME"}}

placeholder

Gets an placeholder variable. The braces ({}) have to be omitted.

{{placeholder "http.request.uri.path"}}
{{placeholder "http.error.status_code"}}

As a shortcut, ph is an alias for placeholder.

{{ph "http.request.method"}}

.Host

Returns the hostname portion (no port) of the Host header of the HTTP request.

{{.Host}}

httpInclude

Includes the contents of another file, and renders it in-place, by making a virtual HTTP request (also known as a sub-request). The URI path must exist on the same virtual server because the request does not use sockets; instead, the request is crafted in memory and the handler is invoked directly for increased efficiency.

{{httpInclude "/foo/bar?q=val"}}

import

Reads and returns the contents of another file, and parses it as a template, adding any template definitions to the template stack. If there are no definitions, the filepath will be the definition name. Any {{ define }} blocks will be accessible by {{ template }} or {{ block }}. Imports must happen before the template or block action is called. Note that the contents are NOT escaped, so you should only import trusted template files.

filename.html

{{ define "main" }}
content
{{ end }}

index.html

{{ import "/path/to/filename.html" }}
{{ template "main" }}

include

Includes the contents of another file, rendering it in-place. Optionally can pass key-value pairs as arguments to be accessed by the included file. Use .Args N to access the N-th argument, 0-indexed. Note that the contents are NOT escaped, so you should only include trusted template files.

{{include "path/to/file.html"}}  // no arguments
{{include "path/to/file.html" "arg0" 1 "value 2"}}  // with arguments

readFile

Reads and returns the contents of another file, as-is. Note that the contents are NOT escaped, so you should only read trusted files.

{{readFile "path/to/file.html"}}

listFiles

Returns a list of the files in the given directory, which is relative to the template context's file root.

{{listFiles "/mydir"}}

markdown

Renders the given Markdown text as HTML and returns it. This uses the Goldmark library, which is CommonMark compliant. It also has these extensions enabled: GitHub Flavored Markdown, Footnote, and syntax highlighting provided by Chroma.

{{markdown "My _markdown_ text"}}

.RemoteIP

Returns the connection's IP address.

{{.RemoteIP}}

.ClientIP

Returns the real client's IP address, if trusted_proxies was configured, otherwise returns the connection's IP address.

{{.ClientIP}}

.Req

Accesses the current HTTP request, which has various fields, including:

• .Method - the method
• .URL - the URL, which in turn has component fields (Scheme, Host, Path, etc.)
• .Header - the header fields
• .Host - the Host or :authority header of the request

{{.Req.Header.Get "User-Agent"}}

.OriginalReq

Like .Req, except it accesses the original HTTP request before rewrites or other internal modifications.

.RespHeader.Add

Adds a header field to the HTTP response.

{{.RespHeader.Add "Field-Name" "val"}}

.RespHeader.Del

Deletes a header field on the HTTP response.

{{.RespHeader.Del "Field-Name"}}

.RespHeader.Set

Sets a header field on the HTTP response, replacing any existing value.

{{.RespHeader.Set "Field-Name" "val"}}

httpError

Returns an error with the given status code to the HTTP handler chain.

{{if not (fileExists $includedFile)}}{{httpError 404}}{{end}}

splitFrontMatter

Splits front matter out from the body. Front matter is metadata that appears at the very beginning of a file or string. Front matter can be in YAML, TOML, or JSON formats:

TOML front matter starts and ends with +++:

+++
template = "blog"
title = "Blog Homepage"
sitename = "A Caddy site"
+++

YAML is surrounded by ---:

---
template: blog
title: Blog Homepage
sitename: A Caddy site
---

JSON is simply { and }:

{
"template": "blog",
"title": "Blog Homepage",
"sitename": "A Caddy site"
}

The resulting front matter will be made available like so:

• .Meta to access the metadata fields, for example: {{$parsed.Meta.title}}
• .Body to access the body after the front matter, for example: {{markdown $parsed.Body}}

stripHTML

Removes HTML from a string.

{{stripHTML "Shows <b>only</b> text content"}}

humanize

Transforms size and time inputs to a human readable format. This uses the go-humanize library.

The first argument must be a format type, and the last argument is the input, or the input can be piped in. The supported format types are:

• size which turns an integer amount of bytes into a string like 2.3 MB
• time which turns a time string into a relative time string like 2 weeks ago

For the time format, the layout for parsing the input can be configured by appending a colon : followed by the desired time layout. You can find the documentation on time layouts in Go's docs. The default time layout is RFC1123Z, i.e. Mon, 02 Jan 2006 15:04:05 -0700.

pathEscape

Passes a string through url.PathEscape, replacing characters that have special meaning in URL path parameters (?, &, %).

Useful e.g. to include filenames containing these characters in URL path parameters, or use them as an img element's src attribute.

{{pathEscape "50%_valid_filename?.jpg"}}

{{humanize "size" "2048000"}}
{{placeholder "http.response.header.Content-Length" | humanize "size"}}
{{humanize "time" "Fri, 05 May 2022 15:04:05 +0200"}}
{{humanize "time:2006-Jan-02" "2022-May-05"}}

Field name	Field type	Comment
FileRoot	string	The root path from which to load files. Required if template functions accessing the file system are used (such as include). Default is {http.vars.root} if set, or current working directory otherwise.
MIMETypes	[]string	The MIME types for which to render templates. It is important to use this if the route matchers do not exclude images or other binary files. Default is text/plain, text/markdown, and text/html.
Delimiters	[]string	The template action delimiters. If set, must be precisely two elements: the opening and closing delimiters. Default: ["{{", "}}"]
ExtensionsRaw	caddy.ModuleMap	Extensions adds functions to the template's func map. These often act as components on web pages, for example.
customFuncs	[]template.FuncMap	No comment on field.
logger	*zap.Logger	No comment on field.

WrappedHeader wraps niladic functions so that they can be used in templates. (Template functions must return a value.)

Field name	Field type	Comment
	http.Header	No comment on field.

This type doesn't have documentation.

Field name	Field type	Comment
FenceOpen	string	No comment on field.
FenceClose	[]string	No comment on field.
ParseFunc	func(input []byte) (map[string]any, error)	No comment on field.

This type doesn't have documentation.

Field name	Field type	Comment
Meta	map[string]any	No comment on field.
Body	string	No comment on field.

virtualResponseWriter is used in virtualized HTTP requests that templates may execute.

Field name	Field type	Comment
status	int	No comment on field.
header	http.Header	No comment on field.
body	*bytes.Buffer	No comment on field.

NewTemplate returns a new template intended to be evaluated with this context, as it is initialized with configuration from this context.

Uses: template.FuncMap, template.New, url.PathEscape.

Provision provisions t.

Uses: fmt.Errorf.

Uses: bytes.Buffer, caddyhttp.NewResponseRecorder, http.Header, strconv.Itoa, strings.Contains.

Validate ensures t has a valid configuration.

Uses: fmt.Errorf.

ClientIP gets the IP address of the real client making the request if the request is trusted (see trusted_proxies), otherwise returns the connection's remote IP.

Uses: caddyhttp.ClientIPVarKey, caddyhttp.GetVar, net.SplitHostPort.

Cookie gets the value of a cookie with name.

Host returns the hostname portion of the Host header from the HTTP request.

Uses: net.SplitHostPort, strings.Contains.

OriginalReq returns the original, unmodified, un-rewritten request as it originally came in over the wire.

Uses: caddyhttp.OriginalRequestCtxKey, http.Request.

RemoteIP gets the IP address of the connection's remote IP.

Uses: net.SplitHostPort.

CaddyModule returns the Caddy module information.

Add adds a header field value, appending val to existing values for that field. It returns an empty string.

Del deletes a header field. It returns an empty string.

Set sets a header field value, overwriting any other values for that field. It returns an empty string.

templates [<matcher>] {
    mime <types...>
    between <open_delim> <close_delim>
    root <path>
}

This type doesn't have documentation.