jekyll-paginate-v2 1.2.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 80659d18067d2e6e70c308778083386e55baa867
-  data.tar.gz: 24d4018f4b1df421583e0412079e6fd71cb6ab9d
+  metadata.gz: e40078ff1d6e37ea3e12e5c00a6d19918532cc9f
+  data.tar.gz: 5b48bf3d7056f77ffe6a5644127bd8f48460d75c
 SHA512:
-  metadata.gz: 8a49c16c2a1e5e450e39a169362a4702ec769160338a9ad081ad0e3a84a4c118117e3ea6039debdd16f05d2d3de35b7837558bf967ac06b5a62f5ecbf065a849
-  data.tar.gz: f34d20de449ce50b39f7c6015425f0f9f8b4ee52d7e04b9faaf5961470b90e6c2e4c0e6fc486714b7c11d29e20394c09c6d25e9c6e690cac14a5186938801594
+  metadata.gz: 4b30be9bf65547b50bb37bbb088e3f6836efcae6f0e5ea44c44109502b38b1f078f89f5676afdef1555a852cfe6c8efc8f6f04f31a90eeaed164272445a8c31f
+  data.tar.gz: 84286d55555990445f81c14245e7371277ad12d6d1867f32129f709f4f51dd9a4792619e5268b3761de80f757bee72c905b13e157d81a2da2d1f76eb65b0cfd9

data/README.md

@@ -18,7 +18,7 @@ gem install jekyll-paginate-v2
 
 Update your [_config.yml](#site-configuration) and [pages](#page-configuration).
 
-> Although backwards compatible, this gem needs slightly extended [site yml](#site-configuration) configuration and adds miniscule new front-matter for the [paging templates](#page-configuration) configuration elements.
+> Although fully backwards compatible, to enable the new features this gem needs slightly extended [site yml](#site-configuration) configuration and miniscule additional new front-matter for the [paging templates](#page-configuration) configuration elements.
 
 Now you're ready to run `jekyll serve` and your paginated files should be generated.
 
@@ -36,15 +36,12 @@ In addition to all the features offered by the older [jekyll-paginate gem](https
 7. Fully customizable permalink format. E.g `/page:num/` or `/page/:num/` or `/:num/` or really anything you want.
 8. Optional title suffix for paginated pages (e.g. _Index - Page 2_)
 
-All this while being fully backwards compatible with the old [jekyll-paginate](https://github.com/jekyll/jekyll-paginate) gem (requires minimal additional front-matter, see [page-configuration](#page-configuration)).
+All this while being fully backwards compatible with the old [jekyll-paginate](https://github.com/jekyll/jekyll-paginate) gem.
 
 ## Issues / to-be-completed
-* Not fully compatible with the old jekyll-paginate plugin configuration yet.
 * Incomplete unit-tests 
 * Missing integration tests [#2](https://github.com/jekyll/jekyll-paginate/pull/2)
 * Missing more detailed examples
-* Code is still too tightly coupled with `site` [#26](https://github.com/jekyll/jekyll-paginate/issues/26)
-* Unable to paginate _pages_ (still under consideration)
 * Unable to auto-generate category/tag/language pagination pages. Still requires programmer to specify the pages him/herself.
 * _Exclude_ filter not implemented [#6](https://github.com/jekyll/jekyll-paginate/issues/6) 
 
@@ -107,6 +104,20 @@ pagination:
 ############################################################
 ```
 
+### 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. 
+
+> You cannot run both the new pagination logic and the old one at the same time
+
+The following `_config.yml` settings are honored when running this gem in compatability mode
+
+``` yml
+paginate: 8
+paginate_path: "/legacy/page:num/"
+```
+
+See more about the old style of pagination at the [jekyll-paginate](https://github.com/jekyll/jekyll-paginate) page.
+
 ## Page configuration
 
 To enable pagination on a page (i.e. make that page a template for pagination) then simply include the minimal pagination configuration in the page front-matter:
@@ -161,9 +172,12 @@ Enabling pagination for specific categories, tags or locales is as simple as add
 Filter single category 'software'
 
 ``` yml
+---
+layout: post
 pagination: 
   enabled: true
   category: software
+---
 ```
 
 Filter multiple categories (lists only posts belonging to all categories)

data/jekyll-paginate-v2.gemspec

@@ -7,14 +7,14 @@ Gem::Specification.new do |spec|
   spec.name          = "jekyll-paginate-v2"
   spec.version       = Jekyll::PaginateV2::VERSION
   spec.platform      = Gem::Platform::RUBY
-  spec.date          = '2016-11-19'
+  spec.date          = DateTime.now.strftime('%Y-%m-%d')
   spec.authors       = ["Sverrir Sigmundarson"]
   spec.email         = ["jekyll@sverrirs.com"]
   spec.homepage      = "https://github.com/sverrirs/jekyll-paginate-v2"
   spec.license       = "MIT"
 
   spec.summary       = %q{Pagination Generator for Jekyll 3}
-  spec.description   = %q{An enhanced in-place replacement for the previously built-in jekyll-paginate gem offering full backwards compatability as well as a slew of new frequently requested features}
+  spec.description   = %q{An enhanced zero-configuration in-place replacement for the now decomissioned built-in jekyll-paginate gem. This pagination gem offers full backwards compatability as well as a slew of new frequently requested features with minimal additional site and page configuration.}
   
   spec.files         = `git ls-files -z`.split("\x0")
   #spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }

data/lib/jekyll-paginate-v2.rb

@@ -11,6 +11,7 @@
 
 require "jekyll-paginate-v2/version"
 require "jekyll-paginate-v2/defaults"
+require "jekyll-paginate-v2/compatibilityUtils"
 require "jekyll-paginate-v2/utils"
 require "jekyll-paginate-v2/paginator"
 require "jekyll-paginate-v2/paginationModel"

data/lib/jekyll-paginate-v2/compatibilityUtils.rb

@@ -0,0 +1,67 @@
+module Jekyll 
+  module PaginateV2
+
+    #
+    # Static utility functions that provide backwards compatibility with the old 
+    # jekyll-paginate gem that this new version superseeds (this code is here to ensure)
+    # that sites still running the old gem work without problems
+    # (REMOVE AFTER 2018-01-01)
+    #
+    class CompatibilityUtils
+
+      # Public: Find the Jekyll::Page which will act as the pager template
+      #
+      # Returns the Jekyll::Page which will act as the pager template
+      def self.template_page(site_pages, config_source, config_paginate_path)
+        site_pages.select do |page|
+          CompatibilityUtils.pagination_candidate?(config_source, config_paginate_path, page)
+        end.sort do |one, two|
+          two.path.size <=> one.path.size
+        end.first
+      end
+
+      # Static: Determine if a page is a possible candidate to be a template page.
+      #         Page's name must be `index.html` and exist in any of the directories
+      #         between the site source and `paginate_path`.
+      def self.pagination_candidate?(config_source, config_paginate_path, page)
+        page_dir = File.dirname(File.expand_path(Utils.remove_leading_slash(page.path), config_source))
+        paginate_path = Utils.remove_leading_slash(config_paginate_path)
+        paginate_path = File.expand_path(paginate_path, config_source)
+        page.name == 'index.html' && CompatibilityUtils.in_hierarchy(config_source, page_dir, File.dirname(paginate_path))
+      end
+
+      # Determine if the subdirectories of the two paths are the same relative to source
+      #
+      # source        - the site source
+      # page_dir      - the directory of the Jekyll::Page
+      # paginate_path - the absolute paginate path (from root of FS)
+      #
+      # Returns whether the subdirectories are the same relative to source
+      def self.in_hierarchy(source, page_dir, paginate_path)
+        return false if paginate_path == File.dirname(paginate_path)
+        return false if paginate_path == Pathname.new(source).parent
+        page_dir == paginate_path ||
+          CompatibilityUtils.in_hierarchy(source, page_dir, File.dirname(paginate_path))
+      end
+
+      # 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.
+      #
+      def self.paginate(legacy_config, all_posts, page, &page_create_proc )
+        pages = Utils.calculate_number_of_pages(all_posts, legacy_config['per_page'].to_i)
+        (1..pages).each do |num_page|
+          pager = Paginator.new( legacy_config['per_page'], legacy_config['permalink'], all_posts, num_page, pages, page.url )
+          if num_page > 1
+            newpage = page_create_proc.call( page.dir, page.name )
+            newpage.pager = pager
+            newpage.dir = Utils.paginate_path(page.url, num_page, legacy_config['permalink'])
+          else
+            page.pager = pager
+          end
+        end
+      end
+
+    end # class CompatibilityUtils
+  end # module PaginateV2
+end # module Jekyll

data/lib/jekyll-paginate-v2/defaults.rb

@@ -11,7 +11,8 @@ module Jekyll
       'page_num'     => 1,
       'sort_reverse' => false,
       'sort_field'   => 'date',
-      'limit'        => 0 # Limit how many content objects to paginate (default: 0, means all)
+      'limit'        => 0, # Limit how many content objects to paginate (default: 0, means all)
+      'legacy'       => false # Internal value, do not use (will be removed after 2018-01-01)
     }
 
   end # module PaginateV2

data/lib/jekyll-paginate-v2/paginationGenerator.rb

@@ -22,10 +22,30 @@ module Jekyll
 
         # Retrieve and merge the pagination configuration from the site yml file
         default_config = DEFAULT.merge(site.config['pagination'] || {})
-        
+
+        # Compatibility Note: (REMOVE AFTER 2018-01-01)
+        # If the legacy paginate logic is configured then read those values and merge with config
+        if !site.config['paginate'].nil?
+          # You cannot run both the new code and the old code side by side
+          if !site.config['pagination'].nil?
+            err_msg = "The new jekyll-paginate-v2 and the old jekyll-paginate logic cannot both be configured in the site config at the same time. Please disable the old 'paginate:num' config settings."
+            Jekyll.logger.error err_msg 
+            raise ArgumentError.new(err_msg)
+          end
+
+          default_config['per_page'] = site.config['paginate'].to_i
+          default_config['legacy_source'] = site.config['source']
+          if !site.config['paginate_path'].nil?
+            default_config['permalink'] = site.config['paginate_path'].to_s
+          end
+          # In case of legacy, enable pagination by default
+          default_config['enabled'] = true
+          default_config['legacy'] = true
+        end # Compatibility END (REMOVE AFTER 2018-01-01)
+
         # If disabled then simply quit
         if !default_config['enabled']
-          Jekyll.logger.info "Pagination:","disabled in site.config."
+          Jekyll.logger.info "Pagination:","Disabled in site.config."
           return
         end
         
@@ -57,7 +77,11 @@ module Jekyll
         ################ 3 ####################
         # Now create and call the model with the real-life page creation proc and site data
         model = PaginationModel.new()
-        model.run(default_config, all_pages, site_title, all_posts, &page_create_lambda)
+        if( default_config['legacy'] ) #(REMOVE AFTER 2018-01-01)
+          model.run_compatability(default_config, all_pages, site_title, all_posts, &page_create_lambda) #(REMOVE AFTER 2018-01-01)
+        else
+          model.run(default_config, all_pages, site_title, all_posts, &page_create_lambda)
+        end
 
       end
     end # class PaginationGenerator

data/lib/jekyll-paginate-v2/paginationModel.rb

@@ -4,10 +4,6 @@ module Jekyll
     class PaginationModel
 
       def run(default_config, site_pages, site_title, all_posts, &page_create_proc)
-        #if !block_given?
-        #  raise ArgumentError.new("No page creation block given, cannot continue.")
-        #end
-
         # By default if pagination is enabled we attempt to find all index.html pages in the site
         templates = self.discover_paginate_templates(site_pages)
         if( templates.size.to_i <= 0 )
@@ -25,7 +21,6 @@ module Jekyll
         
         # Now for each template page generate the paginator for it
         for template in templates
-          
           # All pages that should be paginated need to include the pagination config element
           if template.data['pagination'].is_a?(Hash)
             template_config = default_config.merge(template.data['pagination'])
@@ -41,8 +36,30 @@ module Jekyll
             end
           end
         end #for
+      end # function run
+
+      #
+      # This function is here to retain the old compatability logic with the jekyll-paginate gem
+      # no changes should be made to this function and it should be retired and deleted after 2018-01-01
+      # (REMOVE AFTER 2018-01-01)
+      #
+      def run_compatability(legacy_config, site_pages, site_title, all_posts, &page_create_proc)
+
+        if( date = Date.strptime("20180101","%Y%m%d") <= Date.today )
+          raise ArgumentError.new("Legacy jekyll-paginate configuration compatibility mode has expired. Please upgrade to jekyll-paginate-v2 configuration.")
+        end
+
+        Jekyll.logger.warn "Pagination:", "Detected legacy jekyll-paginate logic being run. "+
+        "Please update your configs to use the new pagination logic (gem jekyll-paginate-v2). This compatibility function "+
+        "will stop working after Jan 1st 2018 and your site build will throw an error."
         
-      end # function generate
+        if template = CompatibilityUtils.template_page(site_pages, legacy_config['legacy_source'], legacy_config['permalink'])
+          CompatibilityUtils.paginate(legacy_config, all_posts, template, &page_create_proc)
+        else
+          Jekyll.logger.warn "Pagination:", "Legacy pagination is enabled, but I couldn't find " +
+          "an index.html page to use as the pagination template. Skipping pagination."
+        end
+      end # function run_compatability (REMOVE AFTER 2018-01-01)
       
       #
       # Rolls through all the pages passed in and finds all pages that have pagination enabled on them.
@@ -185,7 +202,7 @@ module Jekyll
         end
                
         # Calculate the max number of pagination-pages based on the configured per page value
-        total_pages = self.calculate_number_of_pages(using_posts, config['per_page'])
+        total_pages = Utils.calculate_number_of_pages(using_posts, config['per_page'])
         
         # If a upper limit is set on the number of total pagination pages then impose that now
         if config['limit'] && config['limit'].to_i > 0 && config['limit'].to_i < total_pages
@@ -216,17 +233,7 @@ module Jekyll
           end
         end
       end # function paginate
-      
-      # Calculate the number of pages.
-      #
-      # all_posts - The Array of all Posts.
-      # per_page  - The Integer of entries per page.
-      #
-      # Returns the Integer number of pages.
-      def calculate_number_of_pages(all_posts, per_page)
-        (all_posts.size.to_f / per_page.to_i).ceil
-      end
-      
+
     end # class PaginationV2
 
   end # module PaginateV2

data/lib/jekyll-paginate-v2/utils.rb

@@ -7,6 +7,16 @@ module Jekyll
     #
     class Utils
 
+      # Static: Calculate the number of pages.
+      #
+      # all_posts - The Array of all Posts.
+      # per_page  - The Integer of entries per page.
+      #
+      # Returns the Integer number of pages.
+      def self.calculate_number_of_pages(all_posts, per_page)
+        (all_posts.size.to_f / per_page.to_i).ceil
+      end
+
       # Static: Return the pagination path of the page
       #
       # site     - the Jekyll::Site object

data/lib/jekyll-paginate-v2/version.rb

@@ -1,5 +1,5 @@
 module Jekyll
   module PaginateV2
-    VERSION = "1.2.0"
+    VERSION = "1.3.1"
   end
 end

data/spec/spec_helper.rb

@@ -5,6 +5,7 @@ require 'jekyll'
 require_relative '../lib/jekyll-paginate-v2/version'
 require_relative '../lib/jekyll-paginate-v2/defaults'
 require_relative '../lib/jekyll-paginate-v2/utils'
+require_relative '../lib/jekyll-paginate-v2/compatibilityUtils'
 require_relative '../lib/jekyll-paginate-v2/paginator'
 require_relative '../lib/jekyll-paginate-v2/paginationModel'
 require_relative '../lib/jekyll-paginate-v2/paginationGenerator'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-paginate-v2
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.1
 platform: ruby
 authors:
 - Sverrir Sigmundarson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-11-19 00:00:00.000000000 Z
+date: 2016-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -52,9 +52,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: An enhanced in-place replacement for the previously built-in jekyll-paginate
-  gem offering full backwards compatability as well as a slew of new frequently requested
-  features
+description: An enhanced zero-configuration in-place replacement for the now decomissioned
+  built-in jekyll-paginate gem. This pagination gem offers full backwards compatability
+  as well as a slew of new frequently requested features with minimal additional site
+  and page configuration.
 email:
 - jekyll@sverrirs.com
 executables: []
@@ -68,6 +69,7 @@ files:
 - Rakefile
 - jekyll-paginate-v2.gemspec
 - lib/jekyll-paginate-v2.rb
+- lib/jekyll-paginate-v2/compatibilityUtils.rb
 - lib/jekyll-paginate-v2/defaults.rb
 - lib/jekyll-paginate-v2/paginationGenerator.rb
 - lib/jekyll-paginate-v2/paginationModel.rb