HUGO
Menu
GitHub 90497 stars Mastodon

Data types

Look up the data types you encounter in Hugo templates, including scalars, collections, safe types, and Hugo objects.

Every value in a template has a data type. The data type determines which functions and methods you can use with the value, and how Hugo prints it. Most function and method pages show the data type of the returned value.

Use the fmt.Printf function with the %T verb to see the data type of a value:

{{ printf "%T" "Hugo" }} → string
{{ printf "%T" 42 }} → int
{{ printf "%T" .Date }} → time.Time

Scalars

A scalar is a single value. Hugo uses these scalar data types:

Data typeDescriptionExample
boolA boolean value, either true or falsetrue
float64A floating point number4.2
int, int64An integer42
stringA sequence of characters"Hugo"

When you combine numbers, the data type of the result depends on the data types of the operands:

  • If both operands are integers, the result is an integer. For example, div 7 2 returns 3, not 3.5.
  • If either operand is a floating point number, the result is a floating point number. For example, div 7.0 2 returns 3.5.

When you compare values, Hugo treats integers and floating point numbers with the same value as equal. For example, eq 1 1.0 returns true. A string is never equal to a number, so eq "1" 1 returns false.

To convert a value from one data type to another, use the cast.ToInt, cast.ToFloat, or cast.ToString function:

{{ int "42" | add 1 }} → 43
{{ printf "%T" (string 42) }} → string

Collections

A collection holds other values. Hugo uses these collection data types:

Data typeDescriptionExample
[]any, []string, []intA slice, a numbered sequence of elementsslice "a" "b" "c"
map[string]anyA map, an unordered group of elements, each indexed by a unique keydict "a" 1 "b" 2

In a data type, [] means “slice of”, and any means that the elements can have any data type. For example, []string is a slice of strings, and map[string]any is a map with string keys and values of any data type. The fmt.Printf function prints any as interface {}, so map[string]any appears as map[string]interface {}.

Create a slice with the collections.Slice function, and a map with the collections.Dictionary function. Some functions return collections too. For example, the strings.Split function returns a []string value.

When you range over a map, Hugo sorts the elements by key:

{{ range $k, $v := dict "b" 2 "a" 1 }}
  {{ $k }}
{{ end }}

The example above renders a and then b.

Map keys are case-sensitive, with one exception. The hmaps.Params data type, returned by the Params method on a Page or Site object, has case-insensitive keys.

Dates and times

Hugo uses these data types for dates and times:

Data typeDescriptionExample
time.TimeA moment in time and a location, either a time zone or a fixed time zone offsettime.AsTime "2023-10-15T13:18:50-07:00"
time.DurationA durationtime.ParseDuration "1h30m"

Every time.Time value has a location, which determines its time zone offset. The location is either a time zone, such as the time zone set by the timeZone setting for a date without an offset or the time zone passed to the time.In function, or an unnamed location fixed at a single offset. A value created from a date/time string with an offset might have an unnamed location, which affects the time zone name when you format it with the time.Format function.

Format and localize a time.Time value with the time.Format function, or use it with any of the time methods. Compare two time.Time values with the compare.Eq, compare.Ne, compare.Lt, compare.Le, compare.Gt, and compare.Ge functions, or with the Equal, Before, and After methods. These functions and methods compare the moments that the values represent, regardless of their time zones. Subtracting one time.Time value from another with the Sub method returns a time.Duration value.

Not every date is a time.Time value. A custom date is a date/time value that you specify in a custom page parameter under the params key in front matter. The data type of a date depends on where it comes from:

SourceData type
The four predefined front matter datestime.Time
The time.AsTime, time.In, and time.Now functionstime.Time
Custom dates in JSON or YAML front matterstring
Quoted custom dates in TOML front matterstring
Unquoted custom dates in TOML front matter, with a time zone offsettime.Time
Unquoted custom dates in TOML front matter, without a time zone offsettoml.LocalDate or toml.LocalDateTime

Only unquoted TOML custom dates with a time zone offset are time.Time values. To use any other custom date with the time methods, convert it to a time.Time value with the time.AsTime function:

{{ printf "%T" .Params.eventDate }} → string
{{ printf "%T" (time.AsTime .Params.eventDate) }} → time.Time

Truthy and falsy values

When you use a value as a condition, such as with the if or with statement, Hugo evaluates it as either truthy or falsy.

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.

Safe types

When the isPlainText setting of an output format is false, as it is for the html output format by default, Hugo escapes values when printing them so that the output is safe to use in HTML. How Hugo escapes a value depends on where you print it, as shown in these examples:

  • In HTML text, <b>A & B</b> becomes &lt;b&gt;A &amp; B&lt;/b&gt;.
  • In a URL attribute such as href, a URL with a scheme other than http, https, or mailto becomes #ZgotmplZ.
  • In a script element, a string becomes a quoted JavaScript string.

To prevent Hugo from rejecting or escaping a value from a trusted source, declare it safe for the place where you print it. Each of these data types marks a value as safe in one context:

Data typeContextFunction
template.CSSA style element or style attributesafe.CSS
template.HTMLHTML textsafe.HTML
template.HTMLAttrAn HTML tag, in place of an attribute name and valuesafe.HTMLAttr
template.JSA script element or event handler attribute, as an expressionsafe.JS
template.JSStrA script element or event handler attribute, as a stringsafe.JSStr
template.URLA URL attribute such as href or srcsafe.URL

A value is safe only in its own context. For example, if you print a template.HTML value in an href attribute, Hugo still escapes it.

Hugo still escapes a safe value as needed for its surroundings. For example, if you print a template.CSS value in a style attribute, Hugo escapes quotation marks and ampersands for the attribute. If you print a template.URL value in an href attribute, Hugo encodes spaces and other special characters in the URL.

Only declare a value safe if it comes from a trusted source, because Hugo does not check the value for unsafe content. Some functions and methods return a template.HTML value, so you do not need to declare their values safe. For example, the transform.Markdownify function and the Content method on a Page object return a template.HTML value, and so does the partials.Include function when isPlainText is false for the partial template’s output format.

When isPlainText is true, Hugo does not escape values, and these data types have no effect.

Hugo objects

An object is a value with its own methods. These are the objects you use most often:

Data typeDescriptionMethods
hmaps.ParamsA map of parameters with case-insensitive keysParams
navigation.MenuA collection of menu entriesMenu
navigation.MenuEntryA menu entryMenu entry
page.OutputFormatAn output format of a pageOutput format
page.PageA pagePage
page.PagerA pager for a paginated list pagePager
page.PagesA collection of pagesPages
page.PagesGroupA collection of pages, grouped by a common valueGroup
page.SiteA siteSite
page.TaxonomyA taxonomy and its termsTaxonomy
resource.ResourceA resource, such as an image or stylesheetResource
resource.ResourcesA collection of resourcesResources
text.PositionA position within a fileSource position
time.DurationA durationDuration
time.TimeA date and timeTime

For most Hugo objects, the fmt.Printf function prints the name of an internal implementation instead of the data type shown above. For example, it prints *hugolib.pageState for a page.Page value. To check whether a value is a page, a site, or a resource, use the reflect.IsPage, reflect.IsSite, or reflect.IsResource function instead.

Source position

A text.Position value is a position within a file, such as the place in a content file where you call a shortcode or where a Markdown element begins. The Position method on a Shortcode object returns a text.Position value, and so does the Position method in each render hook template. Use the value to tell users where to fix a problem when you log an error or warning.

When you print a text.Position value, Hugo formats it using the HUGO_FILE_LOG_FORMAT environment variable. Without this environment variable, the format is ":file::line::col", where the quotation marks are part of the format:

{{ .Position }} → "/home/user/project/content/about.md:11:1"

If you build your project in a terminal that displays colors, Hugo also wraps the printed value in terminal color codes. These codes are useful in error and warning messages, but they appear as extra characters if you render the value to a page.

Use these methods on the text.Position object:

ColumnNumber
(int) Returns the column number, starting at 1.
Filename
(string) Returns the absolute path to the file.
IsValid
(bool) Reports whether the position is valid, meaning that its line number is greater than 0.
LineNumber
(int) Returns the line number, starting at 1.
Offset
(int) Returns the byte offset from the beginning of the file, starting at 0, or -1 if the offset is not available.

To render the position without quotation marks or terminal color codes, format the methods yourself:

{{ with .Position }}
  {{ printf "%s:%d:%d" .Filename .LineNumber .ColumnNumber }} → /home/user/project/content/about.md:11:1
{{ end }}

Any

Some function and method pages show any as the returned data type. This means that the data type depends on the arguments or on the context. For example, the collections.Index function returns an element of a collection, so the data type of the result is the data type of that element.

Similarly, some function pages show []any as the returned data type when the function returns a slice whose data type depends on the arguments. For example, the collections.Where function returns a resource.Resources value when you pass it a resource.Resources value. The collections.Apply function is an exception. It always returns a []any value, regardless of its arguments.