jekyll-paginate-v2-redux 1.7.6

data/README.md

@@ -0,0 +1,77 @@
+# Jekyll::Paginate V2
+
+Pagination gem built specially for Jekyll 3 and newer that is fully backwards compatable and serves as an enhanced replacement for the previously built-in [jekyll-paginate gem](https://github.com/jekyll/jekyll-paginate). View it on [rubygems.org](https://rubygems.org/gems/jekyll-paginate-v2).
+
+[![Gem](https://img.shields.io/gem/v/jekyll-paginate-v2.svg)](https://rubygems.org/gems/jekyll-paginate-v2)
+[![Build Status](https://travis-ci.org/sverrirs/jekyll-paginate-v2.svg?branch=master)](https://travis-ci.org/sverrirs/jekyll-paginate-v2) 
+[![Dependency Status](https://gemnasium.com/badges/github.com/sverrirs/jekyll-paginate-v2.svg)](https://gemnasium.com/github.com/sverrirs/jekyll-paginate-v2)
+[![Code Climate](https://codeclimate.com/github/sverrirs/jekyll-paginate-v2/badges/gpa.svg)](https://codeclimate.com/github/sverrirs/jekyll-paginate-v2)
+[![security](https://hakiri.io/github/sverrirs/jekyll-paginate-v2/master.svg)](https://hakiri.io/github/sverrirs/jekyll-paginate-v2/master)
+[![Gem](https://img.shields.io/gem/dt/jekyll-paginate-v2.svg)](https://rubygems.org/gems/jekyll-paginate-v2)
+
+Reach me at the [project issues](https://github.com/sverrirs/jekyll-paginate-v2/issues) section or via email at [jekyll@sverrirs.com](mailto:jekyll@sverrirs.com).
+
+> The code was based on the original design of [jekyll-paginate](https://github.com/jekyll/jekyll-paginate) and features were sourced from discussions such as [#27](https://github.com/jekyll/jekyll-paginate/issues/27) (thanks [Günter Kits](https://github.com/gynter)).
+
+* [Installation](#installation)
+* [Example Sites](https://github.com/sverrirs/jekyll-paginate-v2/tree/master/examples)
+* [Pagination Generator](#pagination-generator)
+* [Auto-Pages](#auto-pages)
+* [Issues / to-be-completed](#issues--to-be-completed)
+* [How to Contribute](#contributing)
+
+> _"Be excellent to each other"_
+
+:heart:
+
+## Installation
+
+```
+gem install jekyll-paginate-v2
+```
+
+Update your [_config.yml](README-GENERATOR.md#site-configuration) and [pages](README-GENERATOR.md#page-configuration).
+
+> Although fully backwards compatible, to enable the new features this gem needs slightly extended [site yml](README-GENERATOR.md#site-configuration) configuration and miniscule additional new front-matter for the [pages to paginate on](README-GENERATOR.md#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 tips and tricks on how to configure the pagination logic.
+
+
+## Pagination Generator
+
+The [Pagination Generator](README-GENERATOR.md) forms the core of the pagination logic. Calculates and generates the pagination pages.
+
+
+## Auto Pages
+
+The [Auto-Pages](README-AUTOPAGES.md) is an optional feature that auto-magically generates paginated pages for all your tags, categories and collections.
+
+
+## Issues / to-be-completed
+
+* Unit-tests do not cover all critical code paths
+* No integration tests yet [#2](https://github.com/jekyll/jekyll-paginate/pull/2)
+* _Exclude_ filter not implemented [#6](https://github.com/jekyll/jekyll-paginate/issues/6)
+* Elegant way of collecting and printing debug information during pagination
+
+
+I welcome all testers and people willing to give me feedback and code reviews.
+
+## Contributing
+
+> Although this project is small it has a [code of conduct](CODE_OF_CONDUCT.md) that I hope everyone will do their best to follow when contributing to any aspects of this project. Be it discussions, issue reporting, documentation or programming. 
+
+If you don't want to open issues here on Github, send me your feedback by email at [jekyll@sverrirs.com](mailto:jekyll@sverrirs.com).
+
+1. Fork it ( https://github.com/sverrirs/jekyll-paginate-v2/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Run the unit tests (`rake`)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Build the gem locally (`gem build jekyll-paginate-v2.gemspec`)
+6. Test and verify the gem locally (`gem install ./jekyll-paginate-v2-x.x.x.gem`) 
+7. Push to the branch (`git push origin my-new-feature`)
+8. Create new Pull Request
+
+Note: This project uses [semantic versioning](http://semver.org/).

data/Rakefile

@@ -0,0 +1,16 @@
+require 'rake'
+require 'rake/testtask'
+
+#$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), *%w[lib]))
+#require 'lib/jekyll-paginate-v2/version'
+
+Rake::TestTask.new do |t|
+  t.libs.push 'lib'
+  t.libs.push 'specs'
+  t.verbose = true
+  t.pattern = "spec/**/*_spec.rb"
+  t.test_files = FileList['spec/**/*_spec.rb']
+end
+
+desc "Run tests"
+task :default => [:test]

data/jekyll-paginate-v2-redux.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'jekyll-paginate-v2-redux/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "jekyll-paginate-v2-redux"
+  spec.version       = Jekyll::PaginateV2::VERSION
+  spec.platform      = Gem::Platform::RUBY
+  spec.required_ruby_version = '>= 2.0.0'  # Same as Jekyll
+  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-redux"
+  spec.license       = "MIT"
+
+  spec.summary       = %q{Pagination Generator for Jekyll 3}
+  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. Optional features include auto-generation of paginated collection, tag and category pages.}
+  
+  spec.files          = Dir['CODE_OF_CONDUCT.md', 'README*.md', 'LICENSE', 'Rakefile', '*.gemspec', 'Gemfile', 'lib/**/*', 'spec/**/*']
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  # Gem requires Jekyll to work
+  # ~> is the pessimistic operator and is equivalent to '>= 3.0', '< 4.0'
+  spec.add_runtime_dependency "jekyll", "~> 3.0"
+
+  # Development requires more
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake", "~> 10.4"
+  spec.add_development_dependency "minitest", '~> 5.4'
+end

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

@@ -0,0 +1,34 @@
+# Jekyll::Paginate V2 is a gem built for Jekyll 3 that generates pagiatation for posts, collections, categories and tags.
+# 
+# It is based on https://github.com/jekyll/jekyll-paginate, the original Jekyll paginator
+# which was decommissioned in Jekyll 3 release onwards. This code is currently not officially
+# supported on Jekyll versions < 3.0 (although it might work)
+#
+# Author: Sverrir Sigmundarson
+# Site: https://github.com/andrewbents/jekyll-paginate-v2-redux
+# Distributed Under The MIT License (MIT) as described in the LICENSE file
+#   - https://opensource.org/licenses/MIT
+
+require "jekyll-paginate-v2-redux/version"
+# Files needed for the pagination generator
+require "jekyll-paginate-v2-redux/generator/defaults"
+require "jekyll-paginate-v2-redux/generator/compatibilityUtils"
+require "jekyll-paginate-v2-redux/generator/utils"
+require "jekyll-paginate-v2-redux/generator/paginationIndexer"
+require "jekyll-paginate-v2-redux/generator/paginator"
+require "jekyll-paginate-v2-redux/generator/paginationPage"
+require "jekyll-paginate-v2-redux/generator/paginationModel"
+require "jekyll-paginate-v2-redux/generator/paginationGenerator"
+# Files needed for the auto category and tag pages
+require "jekyll-paginate-v2-redux/autopages/utils"
+require "jekyll-paginate-v2-redux/autopages/defaults"
+require "jekyll-paginate-v2-redux/autopages/autoPages"
+require "jekyll-paginate-v2-redux/autopages/pages/baseAutoPage"
+require "jekyll-paginate-v2-redux/autopages/pages/categoryAutoPage"
+require "jekyll-paginate-v2-redux/autopages/pages/collectionAutoPage"
+require "jekyll-paginate-v2-redux/autopages/pages/tagAutoPage"
+
+module Jekyll 
+  module PaginateV2
+  end # module PaginateV2
+end # module Jekyll

data/lib/jekyll-paginate-v2-redux/autopages/autoPages.rb

@@ -0,0 +1,77 @@
+module Jekyll
+  module PaginateV2::AutoPages
+
+    #
+    # When the site has been read then go a head an generate the necessary extra pages
+    # This code is adapted from Stephen Crosby's code https://github.com/stevecrozz
+    Jekyll::Hooks.register :site, :post_read do |site|
+
+      # Get the configuration for the auto pages
+      autopage_config = Jekyll::Utils.deep_merge_hashes(DEFAULT, site.config['autopages'] || {})
+      pagination_config = Jekyll::Utils.deep_merge_hashes(Jekyll::PaginateV2::Generator::DEFAULT, site.config['pagination'] || {})
+
+      # If disabled then don't do anything
+      if !autopage_config['enabled'] || autopage_config['enabled'].nil?
+        Jekyll.logger.info "AutoPages:","Disabled/Not configured in site.config."
+        next ## Break the loop, could be an issue if the hook is called again though??
+      end
+
+      # TODO: Should I detect here and disable if we're running the legacy paginate code???!
+
+      # Simply gather all documents across all pages/posts/collections that we have
+      # we could be generating quite a few empty pages but the logic is just vastly simpler than trying to 
+      # figure out what tag/category belong to which collection.
+      posts_to_use = Utils.collect_all_docs(site.collections)
+
+      ###############################################
+      # Generate the Tag pages if enabled
+      createtagpage_lambda = lambda do | autopage_tag_config, pagination_config, layout_name, tag, tag_original_name |
+        site.pages << TagAutoPage.new(site, site.dest, autopage_tag_config, pagination_config, layout_name, tag, tag_original_name)
+      end
+      autopage_create(autopage_config, pagination_config, posts_to_use, 'tags', 'tags', createtagpage_lambda) # Call the actual function
+      
+
+      ###############################################
+      # Generate the category pages if enabled
+      createcatpage_lambda = lambda do | autopage_cat_config, pagination_config, layout_name, category, category_original_name |
+        site.pages << CategoryAutoPage.new(site, site.dest, autopage_cat_config, pagination_config, layout_name, category, category_original_name)
+      end
+      autopage_create(autopage_config, pagination_config,posts_to_use, 'categories', 'categories', createcatpage_lambda) # Call the actual function
+      
+      ###############################################
+      # Generate the Collection pages if enabled
+      createcolpage_lambda = lambda do | autopage_col_config, pagination_config, layout_name, coll_name, coll_original_name |
+        site.pages << CollectionAutoPage.new(site, site.dest, autopage_col_config, pagination_config, layout_name, coll_name, coll_original_name)
+      end
+      autopage_create(autopage_config, pagination_config,posts_to_use, 'collections', '__coll', createcolpage_lambda) # Call the actual function
+    
+    end # Jekyll::Hooks
+
+
+    # STATIC: this function actually performs the steps to generate the autopages. It uses a lambda function to delegate the creation of the individual
+    #         page types to the calling code (this way all features can reuse the logic).
+    #
+    def self.autopage_create(autopage_config, pagination_config, posts_to_use, configkey_name, indexkey_name, createpage_lambda )
+      if !autopage_config[configkey_name].nil?
+        ap_sub_config = autopage_config[configkey_name]
+        if ap_sub_config ['enabled']
+          Jekyll.logger.info "AutoPages:","Generating #{configkey_name} pages"
+
+          # Roll through all documents in the posts collection and extract the tags
+          index_keys = Utils.ap_index_posts_by(posts_to_use, indexkey_name) # Cannot use just the posts here, must use all things.. posts, collections...
+
+          index_keys.each do |index_key, value|
+            # Iterate over each layout specified in the config
+            ap_sub_config ['layouts'].each do | layout_name |
+              # Use site.dest here as these pages are never created in the actual source but only inside the _site folder
+              createpage_lambda.call(ap_sub_config, pagination_config, layout_name, index_key, value[-1]) # the last item in the value array will be the display name
+            end
+          end
+        else
+          Jekyll.logger.info "AutoPages:","#{configkey_name} pages are disabled/not configured in site.config."
+        end
+      end
+    end
+
+  end # module PaginateV2
+end # module Jekyll

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

@@ -0,0 +1,29 @@
+module Jekyll
+  module PaginateV2::AutoPages
+
+    # The default configuration for the AutoPages
+    DEFAULT = {
+      'enabled'     => false,
+      'tags'        => {
+        'layouts'       => ['autopage_tags.html'],
+        'title'         => 'Posts tagged with :tag',
+        'permalink'     => '/tag/:tag',
+        'enabled'       => true
+
+      },
+      'categories'  => {
+        'layouts'       => ['autopage_category.html'],
+        'title'         => 'Posts in category :cat',
+        'permalink'     => '/category/:cat',
+        'enabled'       => true
+      },
+      'collections' => {
+        'layouts'       => ['autopage_collection.html'],
+        'title'         => 'Posts in collection :coll',
+        'permalink'     => '/collection/:coll',
+        'enabled'       => true
+      } 
+    }
+
+  end # module PaginateV2::AutoPages
+end # module Jekyll

data/lib/jekyll-paginate-v2-redux/autopages/pages/baseAutoPage.rb

@@ -0,0 +1,60 @@
+module Jekyll
+  module PaginateV2::AutoPages
+
+    class BaseAutoPage < Jekyll::Page
+      def initialize(site, base, autopage_config, pagination_config, layout_name, set_autopage_data_lambda, get_autopage_permalink_lambda, get_autopage_title_lambda, display_name)
+        @site = site
+        @base = base
+        @name = 'index.html'
+                
+        layout_dir = '_layouts'
+
+        # Path is only used by the convertible module and accessed below when calling read_yaml
+        # Handling themes stored in a gem
+        @path = if site.in_theme_dir(site.source) == site.source # we're in a theme
+                  site.in_theme_dir(site.source, layout_dir, layout_name)
+                else
+                  site.in_source_dir(site.source, layout_dir, layout_name)
+                end
+        
+        self.process(@name) # Creates the base name and extension
+        self.read_yaml(File.join(site.source, layout_dir), layout_name)
+
+        # Merge the config with any config that might already be defined in the layout
+        pagination_layout_config = Jekyll::Utils.deep_merge_hashes( pagination_config, self.data['pagination'] || {} )
+
+        # Read any possible autopage overrides in the layout page
+        autopage_layout_config = Jekyll::Utils.deep_merge_hashes( autopage_config, self.data['autopages'] || {} )
+        
+        # Now set the page specific pagination data
+        set_autopage_data_lambda.call(pagination_layout_config)
+
+        # Get permalink structure
+        permalink_formatted = get_autopage_permalink_lambda.call(autopage_layout_config['permalink'])
+
+        # Construct the title
+        page_title = autopage_layout_config['title']
+               
+        # NOTE: Should we set this before calling read_yaml as that function validates the permalink structure 
+        self.data['permalink'] = permalink_formatted
+        @url = File.join(permalink_formatted, @name)
+        @dir = permalink_formatted
+
+        self.data['layout'] = File.basename(layout_name, File.extname(layout_name))
+        self.data['title'] = get_autopage_title_lambda.call( page_title )
+        self.data['pagination']  = pagination_layout_config # Store the pagination configuration
+
+        # Add the auto page flag in there to be able to detect the page (necessary when figuring out where to load it from)
+        # TODO: Need to re-think this variable!!!
+        self.data['autopage'] = {"layout_path" => File.join( layout_dir, layout_name ), 'display_name' => display_name.to_s }
+
+        data.default_proc = proc do |_, key|
+          site.frontmatter_defaults.find(File.join(layout_dir, layout_name), type, key)
+        end
+
+        # Trigger a page event
+        #Jekyll::Hooks.trigger :pages, :post_init, self
+      end #function initialize
+    end #class BaseAutoPage
+  end # module PaginateV2
+end # module Jekyll

data/lib/jekyll-paginate-v2-redux/autopages/pages/categoryAutoPage.rb

@@ -0,0 +1,28 @@
+module Jekyll
+  module PaginateV2::AutoPages
+
+    class CategoryAutoPage < BaseAutoPage
+      def initialize(site, base, autopage_config, pagination_config, layout_name, category, category_name)
+
+        # Construc the lambda function to set the config values
+        # this function received the pagination config hash and manipulates it
+        set_autopage_data_lambda = lambda do | in_config |
+          in_config['category'] = category
+        end
+
+        get_autopage_permalink_lambda = lambda do |permalink_pattern|
+          return Utils.format_cat_macro(permalink_pattern, category)
+        end
+
+        get_autopage_title_lambda = lambda do |title_pattern|
+          return Utils.format_cat_macro(title_pattern, category)
+        end
+                
+        # Call the super constuctor with our custom lambda
+        super(site, base, autopage_config, pagination_config, layout_name, set_autopage_data_lambda, get_autopage_permalink_lambda, get_autopage_title_lambda, category_name)
+        
+      end #function initialize
+
+    end #class CategoryAutoPage
+  end # module PaginateV2
+end # module Jekyll

data/lib/jekyll-paginate-v2-redux/autopages/pages/collectionAutoPage.rb

@@ -0,0 +1,28 @@
+module Jekyll
+  module PaginateV2::AutoPages
+
+    class CollectionAutoPage < BaseAutoPage
+      def initialize(site, base, autopage_config, pagination_config, layout_name, collection, collection_name)
+
+        # Construc the lambda function to set the config values
+        # this function received the pagination config hash and manipulates it
+        set_autopage_data_lambda = lambda do | in_config |
+          in_config['collection'] = collection
+        end
+
+        get_autopage_permalink_lambda = lambda do |permalink_pattern|
+          return Utils.format_coll_macro(permalink_pattern, collection)
+        end
+
+        get_autopage_title_lambda = lambda do |title_pattern|
+          return Utils.format_coll_macro(title_pattern, collection)
+        end
+                
+        # Call the super constuctor with our custom lambda
+        super(site, base, autopage_config, pagination_config, layout_name, set_autopage_data_lambda, get_autopage_permalink_lambda, get_autopage_title_lambda, collection_name)
+        
+      end #function initialize
+
+    end #class CollectionAutoPage
+  end # module PaginateV2
+end # module Jekyll

data/lib/jekyll-paginate-v2-redux/autopages/pages/tagAutoPage.rb

@@ -0,0 +1,28 @@
+module Jekyll
+  module PaginateV2::AutoPages
+
+    class TagAutoPage < BaseAutoPage
+      def initialize(site, base, autopage_config, pagination_config, layout_name, tag, tag_name)
+
+        # Construc the lambda function to set the config values, 
+        # this function received the pagination config hash and manipulates it
+        set_autopage_data_lambda = lambda do | config |
+          config['tag'] = tag
+        end
+
+        get_autopage_permalink_lambda = lambda do |permalink_pattern|
+          return Utils.format_tag_macro(permalink_pattern, tag)
+        end
+
+        get_autopage_title_lambda = lambda do |title_pattern|
+          return Utils.format_tag_macro(title_pattern, tag)
+        end
+                
+        # Call the super constuctor with our custom lambda
+        super(site, base, autopage_config, pagination_config, layout_name, set_autopage_data_lambda, get_autopage_permalink_lambda, get_autopage_title_lambda, tag_name)
+        
+      end #function initialize
+
+    end #class TagAutoPage
+  end # module PaginateV2
+end # module Jekyll

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

@@ -0,0 +1,74 @@
+module Jekyll
+  module PaginateV2::AutoPages
+
+    class Utils
+
+      # Static: returns a fully formatted string with the tag macro (:tag) replaced
+      #
+      def self.format_tag_macro(toFormat, tag)
+        return toFormat.sub(':tag', Jekyll::Utils.slugify(tag.to_s))
+      end #function format_tag_macro
+
+      # Static: returns a fully formatted string with the category macro (:cat) replaced
+      #
+      def self.format_cat_macro(toFormat, category)
+        return toFormat.sub(':cat', Jekyll::Utils.slugify(category.to_s))
+      end #function format_cat_macro
+
+      # Static: returns a fully formatted string with the collection macro (:coll) replaced
+      #
+      def self.format_coll_macro(toFormat, collection)
+        return toFormat.sub(':coll', Jekyll::Utils.slugify(collection.to_s))
+      end #function format_coll_macro
+
+      # Static: returns all documents from all collections defined in the hash of collections passed in
+      # excludes all pagination pages though
+      def self.collect_all_docs(site_collections)
+        coll = []
+        for coll_name, coll_data in site_collections
+          if !coll_data.nil? 
+            coll += coll_data.docs.select { |doc| !doc.data.has_key?('pagination') }.each{ |doc| doc.data['__coll'] = coll_name } # Exclude all pagination pages and then for every page store it's collection name
+          end
+        end
+        return coll
+      end
+
+      def self.ap_index_posts_by(all_posts, index_key)
+        return nil if all_posts.nil?
+        return all_posts if index_key.nil?
+        index = {}
+        for post in all_posts
+          next if post.data.nil?
+          next if !post.data.has_key?(index_key)
+          next if post.data[index_key].nil?
+          next if post.data[index_key].size <= 0
+          next if post.data[index_key].to_s.strip.length == 0
+          
+          # Only tags and categories come as premade arrays, locale does not, so convert any data
+          # elements that are strings into arrays
+          post_data = post.data[index_key]
+          if post_data.is_a?(String)
+            post_data = post_data.split(/;|,|\s/)
+          end
+          
+          for key in post_data
+            key = key.strip
+            # If the key is a delimetered list of values 
+            # (meaning the user didn't use an array but a string with commas)
+            for raw_k_split in key.split(/;|,/)
+              k_split = raw_k_split.to_s.downcase.strip #Clean whitespace and junk
+              if !index.has_key?(k_split)
+                # Need to store the original key value here so that I can present it to the users as a page variable they can use (unmodified, e.g. tags not being 'sci-fi' but "Sci-Fi")
+                # Also, only interested in storing all the keys not the pages in this case
+                index[k_split.to_s] = [k_split.to_s, raw_k_split.to_s]
+              end
+            end
+          end
+        end
+        return index
+      end # function index_posts_by
+
+    end # class Utils
+
+  end # module PaginateV2
+end # module Jekyll