newPagelist | Automad

Creates a new pagelist object. The current pagelist will be replaced. A foreach loop can be used to iterate the pagelist object. This method does not have any output. To only update the configuration of the current pagelist, without resetting all other parameters, the pagelist method can be used instead.

<@ newPagelist { options } @>

Options

context String|false: An optionally fixed URL for the context of a pagelist of type breadcrumbs or children. In case this parameter is false, within a loop the context always changes dynamically to the current page. The default is false.
excludeCurrent Boolean: Defines whether the current page is excluded from the pagelist. The default is false.
excludeHidden Boolean: Defines whether hidden pages are excluded from the list. The default is true.
filter String|false: Filters the pagelist by a given tag. The default is false.
limit Integer|null: Limits the pagelist to a maximum number of pages. The default is null.
match json|false: Filters the pagelist by a set of variable/regex combinations. While iterating the set of combinations, all pages where a given variable value is not matching its assigned regex are removed from the pagelist. Note that the set of combinations has to be passed as a JSON formatted string and not as a JSON object. A valid value looks like '{"url": "/(work|blog)/"}' or even '{"url": "@{ regex }"}'. The default is false.
offset Integer: Offsets the selection of pages. The given number of pages will be stripped from the start of the selection. The default is 0.
page Integer|false: The current page of the pagination. This parameter should be used in combination with the limit parameter. The default is false.
search String|false: Filters the pagelist by a given search string. The string can contain multiple keywords separated by spaces. Only pages containing all given keywords get included in the pagelist. The default is false.
sort String|false: Sorts the pagelist by a combination of a variable and order. Multiple combinations can be specified. For example sort: "date desc, title asc" will first sort all pages by date in descending order and then by title in ascending order. Setting this parameter to false will sort the pages by :basename asc. The default is false.
template String|false: Filters the pagelist by template names matching a specified regex. Multiple templates can therefore be matched by using the | operator, like template: "page|home". The default is false.
type String|false: Sets the pagelist type. The default is false.

Examples

To get all pages of the first level and iterate them, like a simple top navigation, you can use the following snippet:

<@ newPagelist { 
  type: 'children', 
  context: '/' 
} @>
<@ foreach in pagelist @>
  <a href="@{ url }">@{ title }</a>
<@ end @>

A more complex example could be a search results page with filters and pagination. Note that it is possible to use query string parameters in the option array for dynamic filtering, searching and pagination (lines 3, 4 and 8).

<@ newPagelist { 
  excludeHidden: false,
  filter: @{ ?filter }, 
  search: @{ ?search },
  sort: ':basename asc',
  template: 'documentation',
  limit: 10,
  page: @{ ?page | def (1) }
} @>

Filtering a pagelist by using the match option can be done as follows. Note that the JSON string is wrapped in single quotes.

<@ newPagelist { 
  match: '{"url": "@{ regex }"}'
} @>

It is also possible to match pages by passing multiple regex patterns.

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