Index file and extensions can be customized site wide, enhancements for

#38, #39 and fixes #35. Documentation updates. Bumping gem version to v1.9.0

README-GENERATOR.md

@@ -27,6 +27,7 @@ The **Generator** forms the core of the pagination logic. It is responsible for
 * [Formatting page titles](#formatting-page-titles)
 * [Reading pagination meta information](#reading-pagination-meta-information)
 * [How to generate a JSON API](#generating-a-json-api)
+* [Renaming pagination file names](#renaming-pagination-file-names)
 * [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)
@@ -94,6 +95,10 @@ pagination:
   # Internally this is set to html by default
   extension: html
 
+  # Optional, the default name of the index file for generated pages (e.g. 'index.html')
+  # Without file extension
+  indexpage: 'index'
+
 ############################################################
 ```
 
@@ -493,54 +498,99 @@ Delivering content via an API is useful, for a lot of the same reasons that pagi
 1. Easy for the user to consume.
 2. Easy for the browser to load.
 
-Paginating content meets both of these requirements, but developers are limited to presenting content statically rather than dynamically.
-
-Some example of dynamic content delivery are:
-
+Paginating content meets both of these requirements, but developers are limited to presenting content statically rather than dynamically. Some example of dynamic content delivery are:
 - Pop up modals
 - Infinite scrolling
 - Multi-tiered pagination (e.g. Netflix UI horizontal scrolling for multiple movie categories)
 
-How do I generate a JSON API for Jekyll?
+### So how do I generate a JSON API for Jekyll?
 
-First, create a new jekyll page. I'm going to call my page `siteAPI.md`.
+First, create a new jekyll page and set its layout to `null` to avoid any extra html to show up.
 
-Next, we're going to use the `extension` option to output the page as a JSON file.
+Next, use the `extension` and `indexpage` option to customize the output of the page and its paginated content as JSON files.
 
 Here's an example page:
 ```
 ---
 layout: null
 permalink: /api
 pagination:
+  permalink: 'feed-:num'
   enabled: true
   extension: json
+  indexpage: 'feed-1'
 ---
 
 {
-  "pages": [
-  {% for post in paginator.posts %}
+  "pages": [{% for post in paginator.posts %}
+    {% if forloop.first != true %},{% endif %}
     {
       "title": "{{ post.title }}",
       "link": "{{ post.url }}"
-    },
-  {% endfor %}
+    }{% endfor %}
   ]
 }
 ```
+Next, run `jekyll build`. This will generate a set of paginated JSON files under the folder `/api`. These JSON files can be loaded via Javascript/AJAX to dynamically load content into your site.
+
+Below's an example set of routes that the configuration would generate:
+- http://localhost:4000/api/feed-1.json
+- http://localhost:4000/api/feed-2.json
+- http://localhost:4000/api/feed-3.json
+
+And here is an example of one of the feed.json files that are created given the markup above
+```
+{
+  "pages": [
+    {
+      "title": "Narcisse Snake Pits",
+      "link": "/2016/11/narcisse-snake-pits.html"
+    },{
+      "title": "Luft-Fahrzeug-Gesellschaft",
+      "link": "/2016/11/luft-fahrzeug-gesellschaft.html"
+    },{
+      "title": "Rotary engine",
+      "link": "/2016/11/rotary-engine.html"
+    }
+  ], 
+  "next": "/api/feed-11.json",
+  "prev": "/api/feed-9.json",
+  "first": "/api/feed-1.json"
+}
+```
+
+For further information see [Example 4](https://github.com/sverrirs/jekyll-paginate-v2/tree/master/examples/04-jsonapi), that project can serve as a starting point for your experiments with this feature.
+
+### How did you generate those 'next', 'prev' and 'first' links?
 
-Next, run `jekyll build`. This will generate a set of paginated JSON files.
+All the normal paginator variables can be used in these JSON feed files. You can use them to achive quite powerful features such as pre-loading and detecting when there are no more feeds to load. 
+
+```
+{% if paginator.next_page %}
+  ,"next": "{{ paginator.next_page_path }}"
+  {% endif %}
+  {% if paginator.last_page %}
+  ,"prev": "{{ paginator.last_page_path }}"
+  {% endif %}
+  {% if paginator.first_page %}
+  ,"first": "{{ paginator.first_page_path }}"
+  {% endif %}
+```
 
-After the build has completed the JSON files will be located in the `_site/api` directory.
-The JSON files can be accessed over HTTP.
+## Renaming pagination file names
+By default the pagination system creates all paginated pages as `index.html`. The system provides an option to override this name and file extension with the 
 
-Here's an example set of routes:
+```yml
+  indexpage: index
+  extension: html
+```
 
-- http://localhost:4000/api/index.json
-- http://localhost:4000/api/page/2/index.json
-- http://localhost:4000/api/page/3/index.json
+If you wanted to generate all pagination files as `default.htm` then the settings should be configured as follows
 
-These routes can be fetched via AJAX to dynamically load content into your site.
+```yml
+  indexpage: default
+  extension: htm
+```
 
 ## Common issues
 

examples/01-typicalblog/_config.yml

@@ -33,6 +33,10 @@ exclude:
 # Produces a cleaner folder structure when using categories
 permalink: /:year/:month/:title.html
 
+# Explicitly turn off the old code
+paginate: nil
+paginate_path: nil
+
 # Pagination Settings
 pagination:
   enabled: true

examples/03-tags/_config.yml

@@ -70,6 +70,8 @@ pagination:
   limit: 0
   sort_field: 'date'
   sort_reverse: true
+ # extension: htm
+ # indexpage: 'default'
   trail: 
     before: 2
     after: 2

examples/04-jsonapi/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.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", "~> 1.7"
+  gem "jekyll-feed"
+end
+
+gem 'wdm', '>= 0.1.0' if Gem.win_platform?

examples/04-jsonapi/README.md

@@ -0,0 +1,100 @@
+# Example 04::Dynamic JSON/AJAX API
+This example site shows how the pagination gem can be used to generate JSON feed files that can be used to provide dynamically loaded content to your website using Javascript and AJAX/XHR calls.
+
+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 site contains a single index.html file and a few example posts. The index.html is responsible for generating the json feed files that contain information about the post content on the website.
+
+Below is an example content from one of the generated json files:
+
+```
+{
+  "pages": [
+    {
+      "title": "Narcisse Snake Pits",
+      "link": "/2016/11/narcisse-snake-pits.html"
+    },{
+      "title": "Luft-Fahrzeug-Gesellschaft",
+      "link": "/2016/11/luft-fahrzeug-gesellschaft.html"
+    },{
+      "title": "Rotary engine",
+      "link": "/2016/11/rotary-engine.html"
+    }
+  ], 
+  "next": "/api/feed-3.json",
+  "prev": "/api/feed-1.json"
+}
+```
+
+## 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
+
+The normal pagination for the site can be added to the  `_config.yml` file as normal. 
+However it is advisable to configure the feed generating pages independantly of the main site pagination configuration.
+
+Therefore the `index.html` page contains the following frontmatter:
+
+
+``` yml
+---
+layout: null
+permalink: /api
+pagination:
+  permalink: 'feed-:num'
+  enabled: true
+  extension: json
+  indexpage: 'feed-1'
+---
+```
+
+## Completing the setup
+Now you need to configure the generation of the JSON contents for your paginated files. Do this by specifying the following code in the body of the `index.html` page
+
+``` yml
+{
+  "pages": [{% for post in paginator.posts %}
+    {% if forloop.first != true %},{% endif %}
+    {
+      "title": "{{ post.title }}",
+      "link": "{{ post.url }}"
+    }{% endfor %}
+  ], 
+  {% if paginator.next_page %}
+  ,"next": "{{ paginator.next_page_path }}"
+  {% endif %}
+  {% if paginator.previous_page %}
+  ,"prev": "{{ paginator.previous_page_path }}"
+  {% endif %}
+}
+```
+
+That is it, no further configuration is needed!
+
+Try building the site yourself using `jekyll build` or `jekyll serve`.
+
+Cheers :heart:

examples/04-jsonapi/_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: [email protected]
+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: ':title - page :num of :max'
+  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/"

examples/04-jsonapi/_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.

examples/04-jsonapi/_posts/2016-11-21-sailing-summer-olympics-1988.md

@@ -0,0 +1,15 @@
+---
+layout: post
+title:  Sailing at the 1988 Summer Olympics
+date:   2016-11-21 19:16:49 +0100
+categories: wikipedia
+---
+
+_From Wikipedia, the free encyclopedia_
+
+Sailing/Yachting is an Olympic sport starting from the 1896 Olympics in Athens, Greece). With the exception of 1904 and possible 1916 sailing was always a part of the Olympic program. The Sailing program of 1988 consisted of a total of eight sailing classes (disciplines). For each class seven races were scheduled from September 20, 1988 to September 27, 1988 of the coast of Busan and was the first time that a separate event was allocated exclusively for women (sailed in the 470 class). The sailing was done on the triangular type Olympic courses.
+
+## Venue
+According to the IOC statutes the contests in all sport disciplines must be held either in, or as close as possible to the city which the IOC has chosen. Since the sailing conditions of the coast near Seoul are not very suitable for Olympic sailing Busan was chosen for the 1988 Sailing event. A total of two race areas were created of the coast of Busan.
+
+Busan in Korea was reportedly a light wind venue but no one realised until too late that this information came from the airport which was located in a sheltered valley. It turned out to be that the 1988 Olympic Games were one of the windiest ever with one day of racing postponed due to too much wind. One day of racing saw around 30 knots of wind with 5 knots of current going against the wind. There was a lot of equipment damage and rescues for many classes resulting in many sailors did not finish and requests for redress.