• Stars
    star
    105
  • Rank 328,196 (Top 7 %)
  • Language
    HTML
  • License
    MIT License
  • Created almost 10 years ago
  • Updated about 7 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A simple paginator for Jekyll sites.

Octopress Paginate

Simple and flexible pagination for Jekyll sites featuring:

  • Simple configuration
  • Paginate posts and collections
  • Page limits (Because who's reading page 35?)
  • Filter by categories or tags
  • Multi-language support (with octopress-multilingual)

Build Status Gem Version License

Installation

If you're using bundler add this gem to your site's Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-paginate'
end

Then install the gem with Bundler

$ bundle

To install manually without bundler:

$ gem install octopress-paginate

Then add the gem to your Jekyll configuration.

gems:
  - octopress-paginate

Usage

To paginate posts, create a page to be used as the pagination template.

---
title: Post Index
paginate: true
---

{% for post in paginator.posts %}
/ do stuff /
{% endfor %}

Paginating collection is almost the same as posts except you need to set the collection to paginate.

---
title: Penguin Index
paginate:
  collection: penguins
---

{% for penguin in paginator.penguins %}
/ do stuff /
{% endfor %}

Multilingual pagination

If you are running a multilingual site with octopress-multilingual, simply set a language for your pagination template and posts will be filtered by that language. For example:

---
Title: "Deutsch Posts"
permalink: /de/posts/ # <- Or wherever makes sense on your site
paginate: true
lang: de  # <- Add a language
---

{% for posts in paginator.posts %}
/ do stuff /
{% endfor %}

That's all there is to it.

Template variables

Just like Jekyll's paginator, your pagination pages will have access to the following liquid variables.

paginator.total_pages          # Number of paginated pages
paginator.total_posts          # Total number of posts being paginated
paginator.per_page             # Posts per page
paginator.limit                # Maximum number of paginated pages
paginator.page                 # Current page number
paginator.previous_page        # Previous page number (nil if first page)
paginator.previous_page_path   # Url for previous page (nil if first page)
paginator.next_page            # Next page number (nil if last page)
paginator.next_page_path       # Next page URL (nil if last page)

# If you're pagination through a collection named `penguins`
pagination.total_penguins      # Total number of peguins being paginated

Configuration

Pagination is configured on a per-page basis under the paginate key in a page's YAML front-matter. Setting paginate: true enables pagination with these defaults.

paginate:
  collection:   posts
  per_page:     10             # maximum number of items per page
  limit:        5              # Maximum number of pages to paginate (false for unlimited)
  permalink:    /page:num/     # pagination path (relative to template page)
  title_suffix: " - page :num" # Append to template's page title
  category:     ''             # Paginate items in this category
  categories:   []             # Paginate items in any of these categories
  tag:          ''             # Paginate items tagged with this tag
  tags:         []             # Paginate items tagged with any of these tags
  reversed:     false          # Reverse the order of the documents

Why set a pagination limit? For sites with lots of posts, this should speed up your build time considerably since Jekyll won't have to generate and write so many additional pages. Additionally, I suspect that it is very uncommon for users to browse paginated post indexes beyond a few pages. If you don't like it, it's easy to disable.

Site-wide pagination defaults

You can set your own site-wide pagination defaults by configuring the pagination key in Jekyll's site config.

pagination:
  limit: false
  per_page: 20
  title_suffix: " (page :num)"

Note: this will only change the defaults. A page's YAML front-matter will override these defaults.

Pagination permalinks

Assume your pagination template page was at /index.html. The second pagination page would be published to /page2/index.html by default. If your template page was at /posts/index.html or if was configured with permalink: /posts/ the second pagination page would be published to /posts/page2/index.html.

Here are some examples:

paginate:
  permalink /page-:num/  # => /page-2/index.html
  permalink /page/:num/  # => /page/2/index.html
  permalink /:num/       # => /2/index.html

You get the idea.

Contributing

  1. Fork it (https://github.com/octopress/paginate/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

More Repositories

1

octopress

Octopress 3.0 – Jekyll's Ferrari
Ruby
1,750
star
2

ink

A core component for building Gem based Jekyll themes.
Ruby
103
star
3

deploy

Deployment for Octopress and Jekyll blogs.
Ruby
75
star
4

minify-html

Minify Jekyll's HTML output
Ruby
71
star
5

multilingual

Write elegant multi-language Jekyll sites
Ruby
70
star
6

debugger

Debug Jekyll sites with a fancy console.
Ruby
51
star
7

autoprefixer

Automatically adds CSS vendor prefixes for all CSS and Sass files in any Jekyll blog.
Ruby
51
star
8

colorator

Colorize your text in the terminal.
Ruby
32
star
9

genesis-theme

A Jekyll theme build on Octopress Ink
CSS
24
star
10

docs

Source for the octopress.org documentation website
Ruby
24
star
11

linkblog

Adds link blogging features, along with some other niceties, to any Jekyll site.
Ruby
20
star
12

docker

A docker image for Octopress
Shell
18
star
13

video-tag

A Jekyll plugin for easy HTML5 video tags
Ruby
18
star
14

octopress.github.com

The Octopress site source
JavaScript
17
star
15

quote-tag

A nice HTML5 blockquote Liquid tag for Jekyll sites.
HTML
17
star
16

social

Social share and follow buttons (or privacy-friendly links)
HTML
16
star
17

codefence

Write beautiful fenced code snippets with in any template.
HTML
16
star
18

date-format

Automatically adds variables with nicely formated dates and time tags to Jekyll posts and pages.
HTML
16
star
19

gist

Embed GitHub gists, support caching, and multiple files per gist.
HTML
13
star
20

feeds

RSS feeds for Jekyll sites, featuring link-blogging and multilingual support.
HTML
11
star
21

code-highlighter

Octopress's core pygments system for rendering code blocks.
Ruby
10
star
22

hooks

Allows other plugins to access page/post content before and after render, and after write.
Ruby
10
star
23

littlefoot

Fancy footnote popovers with native Javascript, for any Jekyll site.
JavaScript
10
star
24

solarized

Style code snippets with Ethan Schoonover's Solarized theme (tweaked a bit).
CSS
10
star
25

classic-theme

The Octopress classic theme.
CoffeeScript
9
star
26

image-tag

A simple image tag for Jekyll sites
Ruby
8
star
27

pullquote-tag

Elegant pullquotes for Jekyll sites.
Ruby
7
star
28

codeblock

Syntax highlighting for Octopress/Jekyll with the {% codeblock %} liquid tag.
Ruby
6
star
29

adn

ADN Timeline displays recent posts on App.net for a user or hashtag. (adapted for Octopress from imathis/adn-timline)
CoffeeScript
5
star
30

render-code

Embed highlighted code snippets from a file.
Ruby
4
star
31

asset-pipeline

Adds your local CSS, Sass, Javascript and Coffeescript files to Octopress Ink's asset pipeline.
Ruby
4
star
32

category-index

A category index generator for Jekyll sites.
Ruby
4
star
33

wrap-tag

A Liquid block tag which makes it easy to wrap an include, render or yield tag with html.
Ruby
3
star
34

escape-code

Automatically liquid tags within code blocks.
Ruby
3
star
35

filter-tag

A Liquid block tag which can conditionally filter its content.
Ruby
3
star
36

filters

A set of Liquid filters used by Octopress.
Ruby
3
star
37

content-for

Add content_for and yield tags to Jekyll with conditional rendering and in-line filters.
Ruby
3
star
38

markdown-tag

Write markdown anywhere on your Jekyll site.
Ruby
3
star
39

include-tag

A powerful include tag with conditional rendering, filters, and more.
Ruby
2
star
40

series

Split posts or pages into a paginate series.
2
star
41

render-tag

Render files inline on any Jekyll page or post.
Ruby
2
star
42

config-tag

A simple Jekyll plugin which reads a configuration and writes a div with HTML5 data attributes.
Ruby
2
star
43

return-tag

Render Liquid variables with conditions and filters.
Ruby
1
star
44

octobopper

Campfire + Hubot + Octopress = <3
CoffeeScript
1
star
45

capture-tag

A more powerful capture liquid tag.
Ruby
1
star
46

comment-tag

A single-line comment tag for Jekyll.
Ruby
1
star