--- title: Pagination permalink: /docs/pagination/ --- With many websites — especially blogs — it’s very common to break the main listing of posts up into smaller lists and display them over multiple pages. Jekyll offers a pagination plugin, so you can automatically generate the appropriate files and folders you need for paginated listings. For Jekyll 3, include the `jekyll-paginate` plugin in your Gemfile and in your `_config.yml` under `plugins`. For Jekyll 2, this is standard.
Pagination only works within HTML files

Pagination does not work from within Markdown files from your Jekyll site. Pagination works when called from within the HTML file, named index.html, which optionally may reside in and produce pagination from within a subdirectory, via the paginate_path configuration value.

## Enable pagination To enable pagination for posts on your blog, add a line to the `_config.yml` file that specifies how many items should be displayed per page: ```yaml paginate: 5 ``` The number should be the maximum number of Posts you’d like to be displayed per-page in the generated site. You may also specify the destination of the pagination pages: ```yaml paginate_path: "/blog/page:num/" ``` This will read in `blog/index.html`, send it each pagination page in Liquid as `paginator` and write the output to `blog/page:num/`, where `:num` is the pagination page number, starting with `2`.
If a site has 12 posts and specifies `paginate: 5`, Jekyll will write `blog/index.html` with the first 5 posts, `blog/page2/index.html` with the next 5 posts and `blog/page3/index.html` with the last 2 posts into the destination directory.
Don't set a permalink

Setting a permalink in the front matter of your blog page will cause pagination to break. Just omit the permalink.

Pagination for categories, tags and collections

The more recent jekyll-paginate-v2 plugin supports more features. See the pagination examples in the repository. This plugin is not supported by GitHub Pages.

## Liquid Attributes Available The pagination plugin exposes the `paginator` liquid object with the following attributes:
Attribute Description

page

current page number

per_page

number of posts per page

posts

a list of posts for the current page

total_posts

total number of posts in the site

total_pages

number of pagination pages

previous_page

page number of the previous pagination page, or nil if no previous page exists

previous_page_path

path of previous pagination page, or nil if no previous page exists

next_page

page number of the next pagination page, or nil if no subsequent page exists

next_page_path

path of next pagination page, or nil if no subsequent page exists

Pagination does not support tags or categories

Pagination pages through every post in the posts variable unless a post has hidden: true in its front matter. It does not currently allow paging over groups of posts linked by a common tag or category. It cannot include any collection of documents because it is restricted to posts.

## Render the paginated Posts The next thing you need to do is to actually display your posts in a list using the `paginator` variable that will now be available to you. You’ll probably want to do this in one of the main pages of your site. Here’s one example of a simple way of rendering paginated Posts in a HTML file: {% raw %} ```liquid --- layout: default title: My Blog --- {% for post in paginator.posts %}

{{ post.title }}

{{ post.date }}

{{ post.content }}
{% endfor %} ``` {% endraw %}
Beware the page one edge-case

Jekyll does not generate a ‘page1’ folder, so the above code will not work when a /page1 link is produced. See below for a way to handle this if it’s a problem for you.

The following HTML snippet should handle page one, and render a list of each page with links to all but the current page. {% raw %} ```liquid {% if paginator.total_pages > 1 %} {% endif %} ``` {% endraw %}