diff --git a/README.md b/README.md index 67fd2fc..1e3788d 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,249 @@ Or install it yourself as: ## Usage -Once the gem is installed on your system, Jekyll will auto-require it. Just set the following configuration +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 `gems`. For Jekyll 2, this is standard. + +
+
Pagination only works within HTML files
+

+ Pagination does not work from within Markdown or Textile 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 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. +

+
+ + +### Enable pagination for multiple pages +If you have a need to have pagination in multiple pages like: + +You have a blog page where you are trying to display a paginated list of blog-posts. And, underneath every post title +you would like to show article-excerpt(summary from first paragraph normally). You also felt that this could be more +verbose so you though to have a more slimmer version of post-list; where there will be only post-title and +published/updated date. + +In short you want to have two versions/templates for pagination. This is how you can achieve:- +```yaml + # in _config.yml + + paginate: 2 # default for all below; will be overridden by `per_page` value + pagination: + - paginate: + path: /blog/page:num/ + per_page: 2 + - paginate: + path: /slim/page:num/ + per_page: 1 +``` +#### Example: +[Example Repo:](https://github.com/shivabhusal/shivabhusal.github.io/blob/master/_config.yml) + +## Liquid Attributes Available + +The pagination plugin exposes the `paginator` liquid object with the following +attributes: + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescription

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 YAML 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: + +```html +{% raw %} +--- +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. + +```html +{% raw %} +{% if paginator.total_pages > 1 %} + +{% endif %} +{% endraw %} +``` ## Contributing diff --git a/lib/jekyll-paginate/pager.rb b/lib/jekyll-paginate/pager.rb index 2f0c647..232c0cb 100644 --- a/lib/jekyll-paginate/pager.rb +++ b/lib/jekyll-paginate/pager.rb @@ -20,7 +20,7 @@ def self.calculate_pages(all_posts, per_page) # # Returns true if pagination is enabled, false otherwise. def self.pagination_enabled?(site) - !site.config['paginate'].nil? && + (site.config['paginate'] || site.config['pagination']) && site.pages.size > 0 end diff --git a/lib/jekyll-paginate/pagination.rb b/lib/jekyll-paginate/pagination.rb index 87d86fb..031761f 100644 --- a/lib/jekyll-paginate/pagination.rb +++ b/lib/jekyll-paginate/pagination.rb @@ -8,21 +8,46 @@ class Pagination < Generator priority :lowest # Generate paginated pages if necessary. - # + # Handles pagination for multiple pages # site - The Site. # # Returns nothing. def generate(site) if Pager.pagination_enabled?(site) - if template = self.class.template_page(site) - paginate(site, template) + multiple_pagination = site.config['pagination'] + + if multiple_pagination + multiple_pagination.each do | config | + paginate = config['paginate'] + per_page = paginate && (paginate['per_page'] || site.config['paginate']) + + site.config['paginate_path'] = paginate['path'] + site.config['paginate'] = per_page if per_page + + handle_pagination(site) if per_page || site.config['paginate'] + end else - Jekyll.logger.warn "Pagination:", "Pagination is enabled, but I couldn't find " + - "an index.html page to use as the pagination template. Skipping pagination." + handle_pagination(site) end end end - + + # Generate paginated pages if necessary. + # + # site - The Site. + # + # Returns nothing. + def handle_pagination(site) + if template = self.class.template_page(site) + paginate(site, template) + else + Jekyll.logger.warn "Pagination:", "Pagination is enabled, but I couldn't find " + + "an index.html page to use as the pagination template. Skipping pagination." + end + end + + private :handle_pagination + # Paginates the blog's posts. Renders the index.html file into paginated # directories, e.g.: page2/index.html, page3/index.html, etc and adds more # site-wide data.