page-filter.md

Selecting site pages

Functions like site_pages in templates or filter/add_to in syndication allow selecting pages from the site.

These parameters can be used to choose pages:

• path: glob or regular expression that matches the file name in the site contents directory. It is used as a file glob (like "blog/*"), unless it starts with ^ or ends with $: then it is considered a regular expression.

• sort: order the results according to the given metadata item. Prepend a dash (-) for reverse sorting. Use url or -url to sort by the url of the page in the website.

• limit is the maximum number of pages to return.

• root is a path limiting matching pages to those under it. You can use "/" to match from the site root. By default it is the path of the directory containing the page from which the search is made.

Any taxonomy defined in the site becomes a possible parameter for filtering, and is a list of categories of that taxonomy: pages must have all those categories to be selected.

Note that in many cases, you may want to omit sort and limit from site_pages and page front matter, and decide sorting and limit in templates with the arrange() filter.

Example:

List blog articles about Debian in a template:

{% for page in site_pages(path="blog/*", tags=["debian"], sort="-date") %}
<li>{{url_for(page)}}</li>
{% endfor %}

Back to reference index