Learn

pages

Display sets of pages in various ways.

{{ pages:listing }}

Displays a list of pages from one or more folders.

Sample Usage

<ul>
    {{ pages:listing }}
        <li>
            <a href="{{ url }}">{{ title }}</a>
        </li>
    {{ /pages:listing }}
</ul>

Parameters

This tag accepts the following parameters:

  • folder — a folder (or pipe-separated list of folders) from which to pull pages, the current folder by default; as of v1.5.3: you can use a * character at the end of your folder to select any page whose folder starts with the text before the *, this will let you look in all subfolders easily
  • taxonomy — a boolean of whether to use the current URL as a taxonomy URL or not, only pulling pages of taxonomy matches when true, false by default
  • show_hidden — a boolean of whether to show hidden files or not, false by default
  • conditions — a comma-separated string of key:value pairs limiting results of the pages pulled back, null by default
  • sort_by — the field to sort the pages list on, order_key by default (order_key being either slug-based or number-based, automatically detected)
  • sort_dir — the direction the sorting should happen, either asc or desc, by default this is dependant on sort_by, it’s a good idea to always set this
  • sortadded in v1.9 allows you to specify one or more sort_by and sort_dir at the same time in one parameter, accepts a comma-separated list of field_name asc|desc
  • limit — the maximum number of pages to display, null (no limit) by default
  • offset — the number of pages to skip over (after sorting has been applied) before displaying the first pages in a listing, 0 by default

Available Tags

Aside from any variable set in your settings, global variables, theme, and content front-matter, the following tags also become available:

  • first — a boolean of whether this is the first page in the listing that will be looped over
  • last — a boolean of whether this is the last page in the listing that will be looped over
  • index — a 1-based iterator counting the number of times the listing has been looped over
  • zero_index — a 0-based iterator counting the number of times the listing has been looped over
  • total_results — the number of results that the listing will print

{{ pages:next }} Added in v1.6.6

Displays the “next” page that would show up in the listing order listing. This is generally a descending order. Think going down or to the right in a list, not “newer” or “more recent”.

Sample Usage

{{ pages:next folder="about/team" }}
    {{ if !no_results }}
        Next up: <a href="{{ url }}">{{ title }}</a>
    {{ endif }}
{{ /pages:next }}

Parameters

This tag accepts all of the standard listing parameters and the following additional parameters:

current

The URL for the piece of content that is considered to be “current.” (This tag will display the next page in the listing after the current one if one exists.)

Default: the current URL

wrap Added in v1.7

When set to true, this tag will wrap around to the other end of the list. In scenarios where there wouldn’t be a next page, the first page will be returned.

Default: false

Available Tags

All tags from the next piece of content are available, as well as one special tag:

{{ has_previous }}

Will return true if this tag’s current content within the list also has previous content. This can be helpful for printing extra stylizing features, such as only putting a hyphen between next and previous links if they both exist. As of v1.7, this tag will be determined based on what wrap is set to on the parent tag.

{{ pages:next folder="about/team" }}
    {{ if !no_results }}
        {{ if has_previous }}
            <span class="delimiter">-</span>
        {{ endif }}

        Next up: <a href="{{ url }}">{{ title }</a>
    {{ endif }}
{{ /pages:next }}

{{ pages:previous }} Added in v1.6.6

Displays the next page that would show up in the listing.

Sample Usage

{{ pages:previous folder="about/team" }}
    {{ if !no_results }}
        Another Team Member: <a href="{{ url }}">{{ title }}</a>
    {{ endif }}
{{ /pages:previous }}

Parameters

This tag accepts all of the standard listing parameters and the following additional parameters:

current

The URL for the piece of content that is considered to be “current.” (This tag will display the previous page in the listing before the current one if one exists.)

Default: the current URL

wrap Added in v1.7

When set to true, this tag will wrap around to the other end of the list. In scenarios where there wouldn’t be a previous page, the last page will be returned.

Default: false

Available Tags

All tags from the next piece of content are available, as well as one special tag:

{{ has_next }}

Will return true if this tag’s current content within the list also has next content. This can be helpful for printing extra stylizing features, such as only putting a hyphen between next and previous links if they both exist. As of v1.7, this tag will be determined based on what wrap is set to on the parent tag.

{{ pages:previous folder="about/team" }}
    {{ if !no_results }}
        Another Team Member: <a href="{{ url }}">{{ title }</a>

        {{ if has_next }}
            <span class="delimiter">-</span>
        {{ endif }}
    {{ endif }}
{{ /pages:previous }}

{{ pages:meld }} Added in v1.7

Meld lets you combine all of the pages found with the given parameters and merge them into one value representative of the whole set.

Sample Usage

Our team has a total of   
{{ pages:meld folder="about/team" field="years_experience" action="sum" precision="0" }}
years of experience.

Parameters

This tag accepts all of the standard listing parameters and the following additional parameters:

field

The field on which to meld.

Default: null

action

The action to perform to meld the content together, currently there are two allowed values:

  • sum will add up all of the field values and return the total
  • average will return the average of all the field values

Default: sum

precision

The number of decimal points to round the number to, although this really only applies to average, setting the precision (even to 0) will run the result through PHP’s number_format function, which will add locale-specific thousands-separators to the outcome.

Default: null

This article was last updated on September 13th, 2016. Find an error? Please let us know!