HUGO
News Docs Themes Community GitHub

with

Binds context (the dot) to the expression and executes the block if expression is truthy.

Syntax

with EXPR

The falsy values are false, 0, any nil pointer or interface value, any array, slice, map, or string of length zero, and zero time.Time values.

Everything else is truthy.

{{ $var := "foo" }}
{{ with $var }}
  {{ . }} → foo
{{ end }}

Use with the else statement:

{{ $var := "foo" }}
{{ with $var }}
  {{ . }} → foo
{{ else }}
  {{ print "var is falsy" }}
{{ end }}

Use else with to check multiple conditions:

{{ $v1 := 0 }}
{{ $v2 := 42 }}
{{ with $v1 }}
  {{ . }}
{{ else with $v2 }}
  {{ . }} → 42
{{ else }}
  {{ print "v1 and v2 are falsy" }}
{{ end }}

Initialize a variable, scoped to the current block:

{{ with $var := 42 }}
  {{ . }} → 42
  {{ $var }} → 42
{{ end }}
{{ $var }} → undefined

Understanding context

At the top of a page template, the context (the dot) is a Page object. Inside of the with block, the context is bound to the value passed to the with statement.

With this contrived example:

{{ with 42 }}
  {{ .Title }}
{{ end }}

Hugo will throw an error:

can't evaluate field Title in type int

The error occurs because we are trying to use the .Title method on an integer instead of a Page object. Inside of the with block, if we want to render the page title, we need to get the context passed into the template.

Use the $ to get the context passed into the template.

This template will render the page title as desired:

{{ with 42 }}
  {{ $.Title }}
{{ end }}

Gaining a thorough understanding of context is critical for anyone writing template code.

See Go’s text/template documentation for more information.