foreach | Automad

The foreach loop iterates collections and lists of files. Depending on the type of list, Automad provides different runtime variables within the code block of the loop to refer to the current item. The :i variable always contains the index of the current iteration.

<@ foreach in ... { options } @>
  ...
<@ else @>
  ...
<@ end @>

The optional else block is processed instead, in case the list is empty. The options object is only used when iterating images in order to resize or crop them.

Pagelist

When iterating the pagelist, the context changes with each iteration to the current page in the loop. All variables that are used inside the loop are then associated with that page.

<ul>
  <@ foreach in pagelist @>
    <li><a href="@{ url }">@{ :i }. @{ title }</a></li>
  <@ else @>
    <li>No pages here!</li>
  <@ end @>
</ul>

:i: The index of the page in the pagelist. In case the pagelist is paginated, the index continues across pages.

Files

In order to iterate a set of files, you can either use the filelist collection or one or more glob patterns, passed as a string or as the value of a variable. When iterating images, options can be passed in order to resize or crop each image.

<@ foreach in '*.jpg, *.png' { width: 400, height: 300, crop: true } @>
  <img
    src="@{ :fileResized }"
    alt="@{ :basename }"
    width="@{ :widthResized }"
    height="@{ :heightResized }"
  >
  <p>@{ :caption }</p>
<@ else @>
  <p>No images found!</p>
<@ end @>

Using a variable instead of a string:

<@ foreach in @{ images | def ('*.jpg') } { width: 400 } @>
  <img src="@{ :fileResized }" alt="@{ :basename }">
<@ end @>

Using the filelist collection:

<@ filelist {
  glob: @{ files | def ('*.png') },
  sort: 'asc'
} @>
<@ foreach in filelist { width: 400 } @>
  <img src="@{ :fileResized }" alt="@{ :basename }">
<@ end @>

Options

width Integer: The maximum width of the resized image.
height Integer: The maximum height of the resized image.
crop Boolean: Defines whether the image is cropped to exactly fit the given width and height. The default is false.

Runtime Variables

:i: The index of the file in the list.
:file: The path of the original file.
:basename: The file name of the original file.
:caption: The caption of the current file.
:width: The original width in pixels.
:height: The original height in pixels.
:fileResized: The path of the resized version of the file. Every size has its own unique file name.
:widthResized: The resulting width of the resized image in pixels.
:heightResized: The resulting height of the resized image in pixels.

Tags and Filters

The tags of the page in the current context can be iterated as follows:

<ul>
  <@ foreach in tags @>
    <li>@{ :tag }</li>
  <@ end @>
</ul>

In order to iterate all tags of the pages in the current pagelist, the filters collection can be used. The following example creates a simple menu to filter a pagelist:

<ul>
  <@ foreach in filters @>
    <li>
      <a href="?<@ queryStringMerge { filter: @{ :filter } } @>">
        @{ :filter }
      </a>
    </li>
  <@ end @>
</ul>