Variables

The actual value of a variable is depending on the current context. In most cases the context is the currently requested page. However, control structures can change the context to any other page during runtime, for example when iterating over a list of pages. In case a variable is not defined in a page's data set, a possibly existing value within the shared data will be used as fallback. Note that also information created by Automad during runtime and parameters of the URL's query string can be used in templates. In case variables have to persist across multiple requests, they can be stored in the session data array.

Page Variables

Page variables reflect the data associated with pages. As mentioned above, the default context is reflected by the URL. However, within loops the context will switch automatically to other pages while iterating. Check out this template of the theme skeleton package for more information. The syntax for outputting variable values within the markup looks like this:

@{ text }

Naming

The name of a variable also determines its input field style in the dashboard. Depending on the start of the name, a corresponding input type is chosen by the following patterns:

• +*: Blocks, like +main — read more here
• checkbox*: Toggle
• color*: Color picker
• date*: Date and time picker
• image*: Image picker — note that images* will be ignored
• text*: Markdown editor
• url*: Link dialog with autocomplete for pages

All other variables a represented by just a simple text area.

Note that variable names can only contain the characters "a-z", "A-Z", "0-9", "-" and "_". The "+" can only be used to indicate a block variable and must be used as the first character in the variable name.

Shared Variables

Conceptually shared variables can be considered as global fallbacks for page variables. They are stored with the shared settings and data. As soon as a variable is used in a template, first it is checked whether that variable is defined in the page's data. If not, Automad will try to use a possibly existing value in the shared data. Shared variables can also be defined during runtime be using the set function.

<@ set { variable: 'Some text ...' } @>
@{ variable }

Note that you can mask variables in either the shared or page settings to have a nice and tidy dashboard with only relevant options and information. Take a look at the masks field in the theme.json documentation to understand how masking works.

Blocks

Compared to all other variable types, block editor variables stand out in the way they stored data. Unlike all other variables, blocks are saved in a structured JSON format. The actual HTML is only rendered when the containing template is rendered. Therefore the block editor doesn't consist of a single textarea only but instead adds a flexible amount of different input fields when needed. In templates, block variables can be used like all other variables too.

@{ +blocks }

It is not required to process the variable content using the markdown pipe function — the blocks are automatically rendered by the template engine. Most of the generated HTML consists of pure HTML tags. However there are some CSS custom properties to control the look of the rendered blocks.

Check out this guide about customizing the look and feel of rendered blocks in your theme.

You can read more about using blocks here.

Query String Parameters

You can access any query string parameter of the current URL by preceding its name with a ?. For example the filter parameter of the URL below can be used as follows:

<# http://yoursite.com/page?filter=all #>
@{ ?filter }

It is good practice to define default values for query string parameters, in case a parameter is not defined or the query string is empty.

@{ ?sort | def ('date desc') }

Again, this template is a very good example of how to use query string parameters to modify the configuration of a pagelist.

Session Variables

Session variables persit across multiple requests and are therefore a good option to store settings like for example the selected language on a website with multilingual content. Session variable names always start with a %.

@{ %variable }

The set function can be used to define session variables. The multilingual content template is a good example for using session variables.

Runtime Variables

Runtime variables are generated by Automad during rendering. They can be used like normal variables in templates. Their name always starts with a :. More here.

@{ :parent }

Reserved Variables

Some variables are always defined by Automad, but can be overriden. You can find a list of all reserved variables here.