---
title: Pagination 
layout: page 
author: Jay Shafstall
---

There are times when an index file will contain more entries than you want to include in a single page.  Pagination allows Urubu to automatically split that page into separate pages in your site.

# Usage

To enable pagination, add an `items_per_page` attribute to the front matter of an index page.  Also add either `items_index` or `items_filter` to say where the list of items should pull from.  

To pull from files in the current directory, with 5 items per page:

```
items_per_page: 5
items_index: this
```

To pull from a different index contents:

```
items_per_page: 5
items_index: news\index.md
```

To filter the contents:

```
items_per_page: 5
items_filter: mysteries time-loop
```

# New Page Variables

Each of the pages generated by pagination will have three new variables available to layouts.

`numpages` - the number of total pages generated  
`prevpage` - the previous page in the chain  
`nextpage` - the next page in the chain  

## Example pagination controls

The following is a sample of generating pagination controls in a layout:

```
      {% if this.numpages %}
			            <div class="block-27">
			              <ul>
      {% if this.prevpage %}
			                <li><a href="{{this.prevpage.url}}">&lt;</a></li>
      {% endif %}
      {% for page in this.pages %}
      {% if page.pagenum == this.thispage %}
			                <li class="active"><span>{{page.pagenum}}</span></li>
      {% else %}
			                <li><a href="{{page.page.url}}">{{page.pagenum}}</a></li>
      {% endif %}
      {% endfor %}
      {% if this.nextpage %}
			                <li><a href="{{this.nextpage.url}}">&gt;</a></li>
      {% endif %}
			              </ul>
			            </div>
      {% endif %}
```
