jekyll-paginate-v2 1.3.3 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d5a8ad5b12fdd974ec99c1a4d4aa6572ed754250
-  data.tar.gz: f7e5182bccff65e50de5588714262bb209d535e7
+  metadata.gz: d2151298586fb30e325abf19b2f4f2feb050581d
+  data.tar.gz: d01e27f2e65eaa820a194e4a261f1668839d75be
 SHA512:
-  metadata.gz: e1ab80baa20145544bcc08d665b9d628c8cc8f651503bccc615ad083a646fc5e6d1bc043cca5d635a7af8a951af789a164ca815a8cde4b4cc68932972f8dd2d7
-  data.tar.gz: 4e8e4aeb771e3ab4b6f9b8ea4f08292e27caad0541be1b23f3fc2a6c4870a64d095c5fea94c1195131d8344eeb2ec6834d89d03f46f9e2c9b330e53b647e9a24
+  metadata.gz: 15b28be37affd98b4b18709747afaf3d7e4ab85cc22541b5549c6b34bedd1e3f531c7e52fc3b20937643371e99fcaa0f15f056a37295d778925342045fc5aef7
+  data.tar.gz: 422190d1e73563def30150c4a4173e4cbbc267b9e123c3bd93cc74da93f99c8b98e2f3c5f22b4be492d3f27169143c0568e5749690e7bf81786efa9eaead52a7

data/.gitignore

@@ -13,4 +13,8 @@ pkg
 rdoc
 spec/reports
 spec/dest
-tmp
+tmp
+_site/
+.sass-cache
+.jekyll-metadata
+.gitignore

data/README.md

@@ -11,6 +11,7 @@ The code was based on the original design of [jekyll-paginate](https://github.co
 
 
 * [Installation](#installation)
+* [Examples](https://github.com/sverrirs/jekyll-paginate-v2/tree/master/examples)
 * [Features](#features)
 * [New site configuration](#site-configuration)
 * [New page configuration](#page-configuration)
@@ -20,9 +21,15 @@ The code was based on the original design of [jekyll-paginate](https://github.co
   + [Filtering tags](#filtering-tags)
   + [Filtering locales](#filtering-locales)
 * [How to paginate on combination of filters](#paginate-on-combination-of-filters)
-* [Specifying configuration overrides](#configuration-overrides)
+* [Overriding site configuration](#configuration-overrides)
+* [Advanced Sorting](#advanced-sorting)
+* [How to detect auto-generated pages](#detecting-generated-pagination-pages)
 * [Common issues](#common-issues)
+    - [Dependency Error after installing](#i-keep-getting-a-dependency-error-when-running-jekyll-serve-after-installing-this-gem)
     - [Bundler error upgrading gem (Bundler::GemNotFound)](#im-getting-a-bundler-error-after-upgrading-the-gem-bundlergemnotfound)
+    - [Pagination pages are not found](#my-pagination-pages-are-not-being-found-couldnt-find-any-pagination-page-skipping-pagination)
+    - [Categories cause excess folder nesting](#my-pages-are-being-nested-multiple-levels-deep)
+    - [Pagination pages overwriting each others pages](#my-pagination-pages-are-overwriting-each-others-pages)
 * [Issues / to-be-completed](#issues--to-be-completed)
 * [How to Contribute](#contributing)
 
@@ -38,6 +45,8 @@ Update your [_config.yml](#site-configuration) and [pages](#page-configuration).
 
 Now you're ready to run `jekyll serve` and your paginated files should be generated.
 
+Please see the [Examples](https://github.com/sverrirs/jekyll-paginate-v2/tree/master/examples) for more information on how to configure the pagination logic.
+
 
 ## Features
 
@@ -149,6 +158,8 @@ The code is fully backwards compatible and you will have access to all the norma
 
 Neat!
 
+Please see the [Examples](https://github.com/sverrirs/jekyll-paginate-v2/tree/master/examples) for more detailed information and working site configurations.
+
 ## Backwards compatibility with jekyll-paginate
 This gem is fully backwards compatible with the old [jekyll-paginate](https://github.com/jekyll/jekyll-paginate) gem and can be used as a zero-configuration replacement for it. If the old site config is detected then the gem will fall back to the old logic of pagination. 
 
@@ -211,6 +222,8 @@ pagination:
   tag: cool, life
 ```
 
+> When specifying tags in your posts make sure that the values are not enclosed in single quotes (double quotes are fine). If they are you will get a cryptic error when generating your site that looks like _"Error: could not read file <FILE>: did not find expected key while parsing a block mapping at line 2 column 1"_
+
 ### Filtering locales
 
 In the case your site offers multiple languages you can include a `locale` item in your post front matter. The paginator can then use this value to filter on
@@ -272,15 +285,85 @@ pagination:
   sort_reverse: false
 ```
 
+## Advanced Sorting
+Sorting can be done by any field that is available in the post front-matter. You can even sort by nested fields.
+
+> When sorting by nested fields separate the fields with a colon `:` character.
+
+As an example, assuming all your posts have the following front-matter
+
+``` yml
+---
+layout: post
+author:
+  name: 
+    first: "John"
+    last: "Smith"
+  born: 1960
+---
+```
+
+You can define pagination sorting on the nested `last` field like so
+
+``` yml
+---
+layout: page
+title: "Authors by first name"
+pagination: 
+  enabled: true
+  sort_field: 'author:name:first'
+---
+```
+
+To sort by the `born` year in decending order (youngest first)
+
+``` yml
+---
+layout: page
+title: "Authors by birth year"
+pagination: 
+  enabled: true
+  sort_field: 'author:born'
+  sort_reverse: true
+---
+```
+
+## Detecting generated pagination pages
+
+To identify the auto-generated pages that are created by the pagination logic when iterating through collections such as `site.pages` the `page.autogen` variable can be used like so
+
+```
+{% for my_page in site.pages %}
+  {% if my_page.title and my_page.autogen == nil %}
+    <h1>{{ my_page.title | escape }}</h1>
+  {% endif %}
+{% endfor %}
+```
+_In this example only pages that have a title and are not auto-generated are included._
+
+This variable is created and assigned the value `page.autogen = "jekyll-paginate-v2"` by the pagination logic. This way you can detect which pages are auto-generated and by what gem. 
+
 ## Common issues
 
-#### I'm getting a bundler error after upgrading the gem (Bundler::GemNotFound)
+### I keep getting a dependency error when running jekyll serve after installing this gem
+
+> Dependency Error: Yikes! It looks like you don't have jekyll-paginate-v2 or one of its dependencies installed...
+
+Check your `Gemfile` in the site root. Ensure that the jekyll-paginate-v2 gem is present in the jekyll_plugins group like the example below. If this group is missing add to the file.
+
+``` ruby
+group :jekyll_plugins do
+  gem "jekyll-paginate-v2"
+end
+```
+
+### I'm getting a bundler error after upgrading the gem (Bundler::GemNotFound)
 
 > bundler/spec_set.rb:95:in `block in materialize': Could not find jekyll-paginate-v2-1.0.0 in any of the sources (Bundler::GemNotFound)
 
 When running `jekyll serve` if you ever get an error similar to the one above the solution is to delete your `Gemfile.lock` file and try again.
 
-#### My pagination pages are not being found (Couldn't find any pagination page. Skipping pagination)
+### My pagination pages are not being found (Couldn't find any pagination page. Skipping pagination)
 
 > Pagination: Is enabled, but I couldn't find any pagination page. Skipping pagination...
 
@@ -288,6 +371,27 @@ Pagination only works inside **pages** they are not supported in the liquid temp
 
 Create a normal page with a `layout:page` in it's front-matter and place the pagination logic there.
 
+### My pages are being nested multiple levels deep
+
+When using `categories` for posts it is advisable to explicitly state a `permalink` structure in your `_config.yml` file. 
+
+```
+permalink: /:year/:month/:title.html
+```
+
+This is because the default behavior in Jekyll is to nest pages for every category that they belong to and Jekyll unfortunately does not understand multi-categories separated with `,` or `;` but instead does all separation on `[space]` only. 
+
+### My pagination pages are overwriting each others pages
+If you specify multiple pages that paginate in the site root then you must give them unique and separate pagination permalink. This link is set in the pagination page front-matter like so
+
+``` yml
+pagination:
+  enabled: true
+  permalink: '/cars/:num/'
+```
+
+Make absolutely sure that your pagination permalink paths do not clash with any other paths in your final site. For simplicity it is recommended that you keep all custom pagination (non root index.html) in a single or multiple separate sub folders under your site root.
+
 ## Issues / to-be-completed
 * Incomplete unit-tests 
 * Missing integration tests [#2](https://github.com/jekyll/jekyll-paginate/pull/2)

data/examples/01-typicalblog/Gemfile

@@ -0,0 +1,28 @@
+source "https://rubygems.org"
+ruby RUBY_VERSION
+
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+gem "jekyll", "3.3.0"
+
+# This is the default theme for new Jekyll sites. You may change this to anything you like.
+gem "minima", "~> 2.0"
+
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+# gem "github-pages", group: :jekyll_plugins
+
+source 'https://rubygems.org'
+
+group :jekyll_plugins do
+  gem "jekyll-paginate-v2"
+  gem "jekyll-feed"
+end
+
+gem 'wdm', '>= 0.1.0' if Gem.win_platform?

data/examples/01-typicalblog/README.md

@@ -0,0 +1,91 @@
+# Example 01::Typical Blog
+This example site shows how the pagination gem can be used on a simple blog site. 
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sverrirs/jekyll-paginate-v2/master/examples/img/01-example-screenshot-main.png" />
+</p>
+
+The site is generated using the jekyll built in new command `jekyll new myblog` and it uses the [default `minima` theme](https://github.com/jekyll/minima).
+
+After generating the pagination gem was installed using
+
+```
+gem install jekyll-paginate-v2
+```
+
+## Structure
+The blog has only one type of posts, blog posts. No category pagination is performed. To implement the pagination for the minima theme the `_layouts/home.html` needed to be modified to call the pagination logic.
+
+The `_includes/header.html` was also overridden to omit listing the auto-generated pagination sites at the top of the header part.
+
+## Setup configuration
+
+The gem is added to the `_config.yml` file under
+``` yml
+gems:
+  - jekyll-paginate-v2
+```
+
+as well as to the `Gemfile` into the main loop
+``` ruby
+group :jekyll_plugins do
+  gem "jekyll-paginate-v2"
+  gem "jekyll-feed"
+end
+```
+
+At this point is is advisable to delete the `Gemfile.lock` file to clear out any potential issues with gem caching and dependency issues (no worries this file will be auto generated for you again).
+
+## Configuring the pagination
+
+Add the pagination configuration to `_config.yml`
+
+``` yml
+# Pagination Settings
+pagination:
+  enabled: true
+  per_page: 3
+  permalink: '/page/:num/'
+  title_suffix: ' - page :num'
+  limit: 0
+  sort_field: 'date'
+  sort_reverse: true
+```
+
+
+Due to the way the entries in the blog utilize multiple categories it is also good to explicitly state the permalink format to avoid excessive nesting of the post pages. So place the following line into the `_config.yml` file as well
+
+``` yml
+# Produces a cleaner folder structure when using categories
+permalink: /:year/:month/:title.html
+```
+
+## Completing the setup
+Now the pagination simply needs to be enabled in the `index.html` file.
+
+``` yml
+---
+layout: home
+pagination: 
+  enabled: true
+---
+```
+
+That is it, no further configuration is needed!
+
+Try building the site yourself using `jekyll build` or `jekyll serve`.
+
+## Testing backwards compatability
+
+In the `_config.yml` file remove or comment out the new `pagination:` configuration and paste/uncomment the following configuration instead. 
+
+``` yml
+# Old jekyll-paginate pagination logic
+paginate: 3
+paginate_path: "/legacy/page:num/"
+```
+Now run `jekyll serve` again and the gem will generate the pagination according to the old jekyll-paginate rules and behavior.
+
+> You must disable the new pagination configuration for the old one to work. You cannot run both configurations at the same time.
+
+Cheers :heart:

data/examples/01-typicalblog/_config.yml

@@ -0,0 +1,51 @@
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing these this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+title: Paginate Example - 01 Typical Blog
+email: jekyll@sverrirs.com
+description: > # this means to ignore newlines until "baseurl:"
+  Shows how the jekyll-paginate-v2 gem can be used on a typical blog created in Jekyll.
+baseurl: "" # the subpath of your site, e.g. /blog
+url: "" # the base hostname & protocol for your site, e.g. http://example.com
+github_username:  sverrirs
+
+# Build settings
+markdown: kramdown
+theme: minima
+gems:
+  - jekyll-paginate-v2
+exclude:
+  - Gemfile
+  - Gemfile.lock
+
+# Produces a cleaner folder structure when using categories
+permalink: /:year/:month/:title.html
+
+# Pagination Settings
+pagination:
+  enabled: true
+  per_page: 3
+  permalink: '/page/:num/'
+  title_suffix: ' - page :num'
+  limit: 0
+  sort_field: 'date'
+  sort_reverse: true
+  
+############################################################
+# Old jekyll-paginate pagination logic
+#   Uncomment thew two entries below to demonstrate how this new gem
+#   retains backwards compatibility with the old pagination logic 
+#paginate: 3
+#paginate_path: "/legacy/page:num/"

data/examples/01-typicalblog/_includes/header.html

@@ -0,0 +1,31 @@
+<header class="site-header" role="banner">
+
+  <div class="wrapper">
+
+    <a class="site-title" href="{{ "/" | relative_url}}">{{ site.title | escape }}</a>
+
+    <nav class="site-nav">
+      <span class="menu-icon">
+        <svg viewBox="0 0 18 15" width="18px" height="15px">
+          <path fill="#424242" d="M18,1.484c0,0.82-0.665,1.484-1.484,1.484H1.484C0.665,2.969,0,2.304,0,1.484l0,0C0,0.665,0.665,0,1.484,0 h15.031C17.335,0,18,0.665,18,1.484L18,1.484z"/>
+          <path fill="#424242" d="M18,7.516C18,8.335,17.335,9,16.516,9H1.484C0.665,9,0,8.335,0,7.516l0,0c0-0.82,0.665-1.484,1.484-1.484 h15.031C17.335,6.031,18,6.696,18,7.516L18,7.516z"/>
+          <path fill="#424242" d="M18,13.516C18,14.335,17.335,15,16.516,15H1.484C0.665,15,0,14.335,0,13.516l0,0 c0-0.82,0.665-1.484,1.484-1.484h15.031C17.335,12.031,18,12.696,18,13.516L18,13.516z"/>
+        </svg>
+      </span>
+
+      <div class="trigger">
+        {% for my_page in site.pages %}
+          <!--
+            my_page.autogen is populated by the pagination logic for all pages
+                            that are automatically created by the gem. Check for non-existence to exclude pagination pages from site.pages iterators
+          -->
+          {% if my_page.title and my_page.autogen == nil %}
+          <a class="page-link" href="{{ my_page.url | relative_url }}">{{ my_page.title | escape }}</a>
+          {% endif %}
+        {% endfor %}
+      </div>
+    </nav>
+
+  </div>
+
+</header>

data/examples/01-typicalblog/_layouts/home.html

@@ -0,0 +1,52 @@
+---
+layout: default
+---
+<!-- Just some nice to have styles for the pager buttons -->
+<style>
+  ul.pager { text-align: center; list-style: none; }
+  ul.pager li {display: inline;border: 1px solid black; padding: 10px; margin: 5px;}
+</style>
+
+<div class="home">
+
+  <h1 class="page-heading">Posts</h1>
+  
+  {{ content }}
+
+  <ul class="post-list">
+    <!-- 
+        Here is the main paginator logic called.
+        All calls to site.posts should be replaced by paginator.posts 
+    -->
+    {% for post in paginator.posts %}
+      <li>
+        <span class="post-meta">{{ post.date | date: "%b %-d, %Y" }}</span>
+
+        <h2>
+          <a class="post-link" href="{{ post.url | relative_url }}">{{ post.title | escape }}</a>
+        </h2>
+      </li>
+    {% endfor %}
+  </ul>
+  
+  <!-- 
+    Showing buttons to move to the next and to the previous list of posts (pager buttons).
+  -->
+  {% if paginator.total_pages > 1 %}
+  <ul class="pager">
+      {% if paginator.previous_page %}
+      <li class="previous">
+          <a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">&larr; Newer Posts</a>
+      </li>
+      {% endif %}
+      {% if paginator.next_page %}
+      <li class="next">
+          <a href="{{ paginator.next_page_path | prepend: site.baseurl | replace: '//', '/' }}">Older Posts &rarr;</a>
+      </li>
+      {% endif %}
+  </ul>
+  {% endif %}
+
+  <p class="rss-subscribe">subscribe <a href="{{ "/feed.xml" | relative_url }}">via RSS</a></p>
+
+</div>

data/examples/01-typicalblog/_posts/2016-11-20-geography-of-minneapolis.md

@@ -0,0 +1,29 @@
+---
+layout: post
+title:  Geography of Minneapolis
+date:   2016-11-20 19:16:49 +0100
+categories: wikipedia
+---
+
+_From Wikipedia, the free encyclopedia_
+
+Minneapolis is the largest city in the state of Minnesota in the United States, and the county seat of Hennepin County.
+
+## Physical
+According to the United States Census Bureau, the city has a total area of 151.3 km² (58.4 mi²). 142.2 km² (54.9 mi²) of it is land and 9.1 km² (3.5 mi²) of it (6.01%) is water. The city center is located just south of 45 degrees north latitude. On the south side of Golden Valley Road just east of Wirth Parkway, a stone containing a weathered plaque marks a point on the 45th parallel.[1] The Mississippi, which runs to the southeast, directed the early growth of the city. Most early streets ran parallel to the river to maximize the amount of land that could be used. Eventually, growth of Minneapolis turned to north-south and east-west streets. Many unique intersections like Seven Corners on the eastern periphery of downtown were formed to translate between the two layouts. Some streets, especially older and more traditionally important ones like Hennepin Avenue and Nicollet Avenue, have both orientations at different points.
+
+## Parks and lakes
+Minneapolis has a large park system consisting of ten square miles (26 km²) of land and water that is interlinked in many places. Theodore Wirth is often credited with the development of this system that brought a playground within the reach of most children and the canopy of trees and boulevards in much of the city. The Mississippi National River and Recreation Area connects regional parks and visitors centers.
+
+Theodore Wirth Park is the largest in the city, shared with Golden Valley, and is about 60% the size of Central Park in New York City. Minnehaha Park is one of the most famous, the site of Minnehaha Falls and cultural heritage events every year. Tower Hill Park in Prospect Park is the home of a 1913 water tower, one of the highest points in Minneapolis.[2]
+
+The Grand Rounds Scenic Byway circles through the city and many of the larger park areas including land along the Mississippi, lakes and scenic areas. A parkway for cars, a bikeway for riders, and a walkway for pedestrians run parallel paths along the 50-mile route. A growing number of bikeways and walkways crisscross the city and interconnect with neighboring cities.
+
+Twenty four small lakes are within the city limits.[3] Among the largest freshwater lakes to the west are Lake Harriet, Lake Calhoun, Lake of the Isles, and Cedar Lake, known together as the "Chain of Lakes". Lake Nokomis and Lake Hiawatha are to the east. Connected by bike, running and walking paths, Minneapolis lakes are used for swimming, fishing, picnics and boating.
+
+## Flora and fauna
+
+### Waterfalls
+The area now occupied by the Twin Cities generally consisted of a 155 foot (47 m) thick layer of St. Peter Sandstone, under a 16 foot (5 m) thick layer of shale, under a 35 foot (11 m) thick layer of Platteville limestone.[4] These layers were the result of an Ordovician Period sea which covered east-central Minnesota 500 million years ago.[4] The hard limestone cap was formed from fossilized shell fish. About 20,000 years ago, the area was covered by the Superior Lobe of the Laurentide ice sheet, which left the St. Croix moraine on the Twin Cities as it receded.[4] Later the Grantsburg Sublobe of the Des Moines Lobe also covered the area.[5] Under these vast layers of ice, tunnel valleys were formed, cutting through the limestone layer with tremendous force, to release ice meltwater and glacier effluence.[6] The result was a series of troughs in the limestone, which were filled by glacial till and outwash deposit as the glaciers receded. Sometimes the sediment would be mixed with huge chunks of ice, which would leave voids in the soil. These voids created basins for the Twin Cities Lakes, such as Harriet and Lake Calhoun.[6] Connecting the city lakes in several north-south arteries are gorges cut through the bedrock, but filled with sand and sediment.
+
+When River Warren Falls receded past the confluence of the much smaller Upper Mississippi River, a new waterfall was created where that river entered the much-lower glacial River Warren. The new falls also receded upstream on the Mississippi, migrating eight miles (12875 m) over 9600 years to where Louis Hennepin first saw it and named St. Anthony Falls in 1680. Due to its value as a power source, this waterfall determined the location of Minneapolis. One branch of the river coming from the west, Minnehaha Creek receded only a few hundred yards from one of the channels of the Mississippi. Minnehaha Falls remains as a picturesque and informative relic of River Warren Falls, and the limestone-over-sandstone construction is readily apparent in its small gorge.