Pagelist | Automad

The pagelist contains by default all pages that are not hidden and has no specific type. Changing the type of the pagelist updates the selection of pages accordingly. The main purpose of the pagelist is to provide an easy way of iterating a defined set of pages using a foreach loop, for example to build navigations, blog indexes, search results or lists of related pages.

<@ newPagelist {
  type: 'children',
  sort: 'date desc',
  filter: @{ ?filter }
} @>
<@ foreach in pagelist @>
  <a href="@{ url }">@{ title }</a>
<@ end @>

Types

false: The default type. All pages of the site.
"children": The direct children of a given page. The parent page can be defined by using the context option. By default, the current context is used.
"siblings": All pages that share the same parent with the current page. Use the excludeCurrent option in order to remove the current page from the list.
"related": All pages that have at least one tag in common with the current page.
"breadcrumbs": A breadcrumb trail to the current page. Note that a breadcrumb trail can't be sorted, filtered or limited.

Sorting and Filtering

A pagelist can be sorted, filtered, searched and paginated, depending on its type. In order to configure the pagelist, you can use the newPagelist and the pagelist functions. While newPagelist resets all options to their defaults before applying the new ones, pagelist only updates the given options and keeps all others.

<@ newPagelist { type: 'children', limit: 10 } @>
<# Only change the sort order and keep all other options. #>
<@ pagelist { sort: 'title asc' } @>

Take a look at the options of the newPagelist function for a full list of all available settings.

Regular Expressions

Aside from filtering a pagelist by tags using the filter option, there is also a more generic way of defining a selection of pages using the match option. It allows for filtering the list of pages by one or more variables using regular expressions. The value of the match option has to be a JSON formatted string. Note that in the example below the JSON string is therefore wrapped in single quotes.

<@ newPagelist {
  match: '{"url": "#(/work|/blog)#", ":level": "/2/"}'
} @>

It is also possible to use variables inside the regular expressions in order to keep a pagelist configurable in the dashboard:

<@ newPagelist {
  match: '{"url": "@{ regex }", ":level": "/2/"}'
} @>

Multilingual Sites

In case language routing is enabled for a multilingual site, a pagelist only includes pages of the currently active language by default. Set the currentLanguageOnly option to false in order to include pages of all languages.

<@ newPagelist { currentLanguageOnly: false } @>

Runtime Variables

There are three runtime variables that are associated with the current configuration of the pagelist:

:pagelistCount: The number of pages in the current pagelist, ignoring the limit and the pagination.
:pagelistDisplayCount: The number of pages that are actually displayed.
:paginationCount: In case a limit of pages per page is defined, :paginationCount reflects the number of pages the pagelist is distributed over.

Examples

The :pagelistCount variable can be used to quickly test whether a pagelist is empty or to create counting badges:

<@ newPagelist {
  type: 'children',
  excludeHidden: false
} @>
<@ if @{ :pagelistCount } @>
  <h2>@{ :pagelistCount } Pages</h2>
<@ end @>

A pagelist can be split into multiple segments with a maximum number of items per page in order to create a pagination. The :paginationCount variable returns the number of segments, depending on the defined limit:

<@ newPagelist {
  limit: 10,
  page: @{ ?page | def (1) }
} @>
<@ for 1 to @{ :paginationCount } @>
  <a href="?<@ queryStringMerge { page: @{ :i } } @>">@{ :i }</a>
<@ end @>