jekyll-paginate-v2-redux 1.7.6

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

@@ -0,0 +1,121 @@
+module Jekyll 
+  module PaginateV2::Generator
+
+    class CompatibilityPaginationPage < Page
+      def initialize(site, base, dir, template_path)
+        @site = site
+        @base = base
+        @dir = dir
+        @template = template_path
+        @name = 'index.html'
+
+        templ_dir = File.dirname(template_path)
+        templ_file = File.basename(template_path)
+
+        # Path is only used by the convertible module and accessed below when calling read_yaml
+        # in our case we have the path point to the original template instead of our faux new pagination page
+        @path = if site.in_theme_dir(base) == base # we're in a theme
+                  site.in_theme_dir(base, templ_dir, templ_file)
+                else
+                  site.in_source_dir(base, templ_dir, templ_file)
+                end
+        
+        self.process(@name)
+        self.read_yaml(templ_dir, templ_file)
+
+        data.default_proc = proc do |_, key|
+          site.frontmatter_defaults.find(File.join(templ_dir, templ_file), type, key)
+        end
+
+      end
+    end # class CompatibilityPaginationPage
+
+    #
+    # 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)
+    #
+    # THIS CLASS IS ADAPTED FROM THE ORIGINAL IMPLEMENTATION AND WILL BE REMOVED, THERE ARE DELIBERATELY NO TESTS FOR THIS CLASS
+    #
+    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_add_lambda )
+        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'], page.url, legacy_config['permalink'], all_posts, num_page, pages )
+          if num_page > 1
+            template_full_path = File.join(page.site.source, page.path)
+            template_dir = File.dirname(page.path)
+            newpage = CompatibilityPaginationPage.new(page.site, page.site.source, template_dir, template_full_path)
+            newpage.pager = pager
+            newpage.dir = CompatibilityUtils.paginate_path(page.url, num_page, legacy_config['permalink'])
+            newpage.data['autogen'] = "jekyll-paginate-v2-redux" # Signals that this page is automatically generated by the pagination logic
+            page_add_lambda.call(newpage)
+          else
+            page.pager = pager
+          end
+        end
+      end
+
+      # Static: Return the pagination path of the page
+      #
+      # site     - the Jekyll::Site object
+      # cur_page_nr - the pagination page number
+      # config - the current configuration in use
+      #
+      # Returns the pagination path as a string
+      def self.paginate_path(template_url, cur_page_nr, permalink_format)
+        return nil if cur_page_nr.nil?
+        return template_url if cur_page_nr <= 1
+        if permalink_format.include?(":num")
+          permalink_format = Utils.format_page_number(permalink_format, cur_page_nr)
+        else
+          raise ArgumentError.new("Invalid pagination path: '#{permalink_format}'. It must include ':num'.")
+        end
+
+        Utils.ensure_leading_slash(permalink_format)
+      end #function paginate_path
+
+    end # class CompatibilityUtils
+  end # module PaginateV2
+end # module Jekyll

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

@@ -0,0 +1,24 @@
+module Jekyll
+  module PaginateV2::Generator
+
+    # The default configuration for the Paginator
+    DEFAULT = {
+      'enabled'      => false,
+      'collection'   => 'posts',
+      'per_page'     => 10,
+      'permalink'    => '/page:num/', # Supports :num as customizable elements
+      'title'        => ':title - page :num', # Supports :num as customizable elements
+      'page_num'     => 1,
+      'sort_reverse' => false,
+      'sort_field'   => 'date',
+      'limit'        => 0, # Limit how many content objects to paginate (default: 0, means all)
+      'trail'        => { 
+          'before' => 0, # Limits how many links to show before the current page in the pagination trail (0, means off, default: 0)
+          'after' => 0,  # Limits how many links to show after the current page in the pagination trail (0 means off, default: 0)
+      },
+      'debug'        => false, # Turns on debug output for the gem
+      'legacy'       => false # Internal value, do not use (will be removed after 2018-01-01)
+    }
+
+  end # module PaginateV2
+end # module Jekyll

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

@@ -0,0 +1,141 @@
+module Jekyll
+  module PaginateV2::Generator
+  
+    #
+    # The main entry point into the generator, called by Jekyll
+    # this function extracts all the necessary information from the jekyll end and passes it into the pagination 
+    # logic. Additionally it also contains all site specific actions that the pagination logic needs access to
+    # (such as how to create new pages)
+    # 
+    class PaginationGenerator < Generator
+      # This generator is safe from arbitrary code execution.
+      safe true
+
+      # This generator should be passive with regard to its execution
+      priority :lowest
+      
+      # Generate paginated pages if necessary (Default entry point)
+      # site - The Site.
+      #
+      # Returns nothing.
+      def generate(site)
+      #begin
+        # Retrieve and merge the pagination configuration from the site yml file
+        default_config = Jekyll::Utils.deep_merge_hashes(DEFAULT, 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-redux and the old jekyll-paginate logic cannot both be configured in the site config at the same time. Please disable the old 'paginate:' 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."
+          return
+        end
+
+        # Handle deprecation of settings and features
+        if( !default_config['title_suffix' ].nil? )
+          Jekyll::Deprecator.deprecation_message "Pagination: The 'title_suffix' configuration has been deprecated. Please use 'title'. See https://github.com/sverrirs/jekyll-paginate-v2/blob/master/README-GENERATOR.md#site-configuration"
+        end
+
+        Jekyll.logger.debug "Pagination:","Starting"
+
+        ################ 0 #################### 
+        # Get all pages in the site (this will be used to find the pagination templates)
+        all_pages = site.pages
+
+        # Get the default title of the site (used as backup when there is no title available for pagination)
+        site_title = site.config['title']
+
+        ################ 1 #################### 
+        # Specify the callback function that returns the correct docs/posts based on the collection name
+        # "posts" are just another collection in Jekyll but a specialized version that require timestamps
+        # This collection is the default and if the user doesn't specify a collection in their front-matter then that is the one we load
+        # If the collection is not found then empty array is returned
+        collection_by_name_lambda = lambda do |collection_name|
+          coll = []
+          if collection_name == "all"
+            # the 'all' collection_name is a special case and includes all collections in the site (except posts!!)
+            # this is useful when you want to list items across multiple collections
+            for coll_name, coll_data in site.collections
+              if( !coll_data.nil? && coll_name != 'posts')
+                coll += coll_data.docs.select { |doc| !doc.data.has_key?('pagination') } # Exclude all pagination pages
+              end
+            end
+          else
+            # Just the one collection requested
+            if !site.collections.has_key?(collection_name)
+              return []
+            end
+
+            coll = site.collections[collection_name].docs.select { |doc| !doc.data.has_key?('pagination') } # Exclude all pagination pages
+          end
+          return coll
+        end
+
+        ################ 2 ####################
+        # Create the proc that constructs the real-life site page
+        # This is necessary to decouple the code from the Jekyll site object
+        page_add_lambda = lambda do | newpage |
+          site.pages << newpage # Add the page to the site so that it is generated correctly
+          return newpage # Return the site to the calling code
+        end
+
+        ################ 2.5 ####################
+        # lambda that removes a page from the site pages list
+        page_remove_lambda = lambda do | page_to_remove |
+          site.pages.delete_if {|page| page == page_to_remove } 
+        end
+
+        ################ 3 ####################
+        # Create a proc that will delegate logging
+        # Decoupling Jekyll specific logging
+        logging_lambda = lambda do | message, type="info" |
+          if type == 'debug'
+            Jekyll.logger.debug "Pagination:","#{message}"
+          elsif type == 'error'
+            Jekyll.logger.error "Pagination:", "#{message}"
+          elsif type == 'warn'
+            Jekyll.logger.warn "Pagination:", "#{message}"
+          else
+            Jekyll.logger.info "Pagination:", "#{message}"
+          end
+        end
+
+        ################ 4 ####################
+        # Now create and call the model with the real-life page creation proc and site data
+        model = PaginationModel.new(logging_lambda, page_add_lambda, page_remove_lambda, collection_by_name_lambda)
+        if( default_config['legacy'] ) #(REMOVE AFTER 2018-01-01)
+          Jekyll.logger.warn "Pagination:", "You are running jekyll-paginate backwards compatible pagination logic. Please ignore all earlier warnings displayed related to the old jekyll-paginate gem."
+          all_posts = site.site_payload['site']['posts'].reject { |post| post['hidden'] }
+          model.run_compatability(default_config, all_pages, site_title, all_posts) #(REMOVE AFTER 2018-01-01)
+        else
+          count = model.run(default_config, all_pages, site_title)
+          Jekyll.logger.info "Pagination:", "Complete, processed #{count} pagination page(s)"
+        end
+
+      #rescue => ex
+      #  puts ex.backtrace
+      #  raise
+      #end
+      end # function generate
+    end # class PaginationGenerator
+
+  end # module PaginateV2
+end # module Jekyll

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

@@ -0,0 +1,93 @@
+module Jekyll
+  module PaginateV2::Generator
+
+    # 
+    # Performs indexing of the posts or collection documents
+    # as well as filtering said collections when requested by the defined filters.
+    class PaginationIndexer
+      #
+      # Create a hash index for all post based on a key in the post.data table
+      #
+      def self.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.to_s.downcase.strip
+            # If the key is a delimetered list of values 
+            # (meaning the user didn't use an array but a string with commas)
+            for k_split in key.split(/;|,/)
+              k_split = k_split.to_s.downcase.strip #Clean whitespace and junk
+              if !index.has_key?(k_split)
+                index[k_split.to_s] = []
+              end
+              index[k_split.to_s] << post
+            end
+          end
+        end
+        return index
+      end # function index_posts_by
+      
+      #
+      # Creates an intersection (only returns common elements)
+      # between multiple arrays
+      #
+      def self.intersect_arrays(first, *rest)
+        return nil if first.nil?
+        return nil if rest.nil?
+        
+        intersect = first
+        rest.each do |item|
+          return [] if item.nil?
+          intersect = intersect & item
+        end
+        return intersect
+      end #function intersect_arrays
+      
+      #
+      # Filters posts based on a keyed source_posts hash of indexed posts and performs a intersection of 
+      # the two sets. Returns only posts that are common between all collections 
+      #
+      def self.read_config_value_and_filter_posts(config, config_key, posts, source_posts)
+        return nil if posts.nil?
+        return nil if source_posts.nil? # If the source is empty then simply don't do anything
+        return posts if config.nil?
+        return posts if !config.has_key?(config_key)
+        return posts if config[config_key].nil?
+        
+        # Get the filter values from the config (this is the cat/tag/locale values that should be filtered on)
+        config_value = config[config_key]
+        
+        # If we're dealing with a delimitered string instead of an array then let's be forgiving
+        if( config_value.is_a?(String))
+          config_value = config_value.split(/;|,/)
+        end
+          
+        # Now for all filter values for the config key, let's remove all items from the posts that
+        # aren't common for all collections that the user wants to filter on
+        for key in config_value
+          key = key.to_s.downcase.strip
+          posts = PaginationIndexer.intersect_arrays(posts, source_posts[key])
+        end
+        
+        # The fully filtered final post list
+        return posts
+      end #function read_config_value_and_filter_posts
+    end #class PaginationIndexer
+
+  end #module PaginateV2
+end #module Jekyll

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

@@ -0,0 +1,358 @@
+module Jekyll
+  module PaginateV2::Generator
+
+    #
+    # The main model for the pagination, handles the orchestration of the pagination and calling all the necessary bits and bobs needed :)
+    #
+    class PaginationModel
+
+      @debug = false # is debug output enabled?
+      @logging_lambda = nil # The lambda to use for logging
+      @page_add_lambda = nil # The lambda used to create pages and add them to the site
+      @page_remove_lambda = nil # Lambda to remove a page from the site.pages collection
+      @collection_by_name_lambda = nil # Lambda to get all documents/posts in a particular collection (by name)
+
+      # ctor
+      def initialize(logging_lambda, page_add_lambda, page_remove_lambda, collection_by_name_lambda)
+        @logging_lambda = logging_lambda
+        @page_add_lambda = page_add_lambda
+        @page_remove_lambda = page_remove_lambda
+        @collection_by_name_lambda = collection_by_name_lambda
+      end
+
+
+      def run(default_config, site_pages, site_title)
+        # 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 )
+          @logging_lambda.call "Is enabled, but I couldn't find any pagination page. Skipping pagination. "+
+          "Pages must have 'pagination: enabled: true' in their front-matter for pagination to work.", "warn"
+          return
+        end
+
+        # 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 = Jekyll::Utils.deep_merge_hashes(default_config, template.data['pagination'] || {})
+
+            # Handling deprecation of configuration values
+            self._fix_deprecated_config_features(template_config)
+
+            @debug = template_config['debug'] # Is debugging enabled on the page level
+
+            self._debug_print_config_info(template_config, template.path)
+            
+            # Only paginate the template if it is explicitly enabled
+            # requiring this makes the logic simpler as I don't need to determine which index pages 
+            # were generated automatically and which weren't
+            if( template_config['enabled'] )
+              if !@debug
+                @logging_lambda.call "found page: "+template.path, 'debug'
+              end
+
+              # Request all documents in all collections that the user has requested 
+              all_posts = self.get_docs_in_collections(template_config['collection'])
+
+              # Create the necessary indexes for the posts
+              all_categories = PaginationIndexer.index_posts_by(all_posts, 'categories')
+              all_categories['posts'] = all_posts; # Populate a category for all posts (this is here for backward compatibility, do not use this as it will be decommissioned 2018-01-01) 
+                                                  # (this is a default and must not be used in the category system)
+              all_tags = PaginationIndexer.index_posts_by(all_posts, 'tags')
+              all_locales = PaginationIndexer.index_posts_by(all_posts, 'locale')
+
+              # TODO: NOTE!!! This whole request for posts and indexing results could be cached to improve performance, leaving like this for now during testing
+
+              # Now construct the pagination data for this template page
+              self.paginate(template, template_config, site_title, all_posts, all_tags, all_categories, all_locales)
+            end
+          end
+        end #for
+
+        # Return the total number of templates found
+        return templates.size.to_i
+      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)
+
+        # Decomissioning error
+        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
+
+        # Two month warning or general notification
+        if( date = Date.strptime("20171101","%Y%m%d") <= Date.today )
+          @logging_lambda.call "Legacy pagination logic will stop working on Jan 1st 2018, update your configs before that time.", "warn"
+        else
+          @logging_lambda.call "Detected legacy jekyll-paginate logic running. "+
+          "Please update your configs to use the jekyll-paginate-v2 logic. This compatibility function "+
+          "will stop working after Jan 1st 2018 and your site build will throw an error.", "warn"
+        end
+
+        if template = CompatibilityUtils.template_page(site_pages, legacy_config['legacy_source'], legacy_config['permalink'])
+          CompatibilityUtils.paginate(legacy_config, all_posts, template, @page_add_lambda)
+        else
+          @logging_lambda.call "Legacy pagination is enabled, but I couldn't find " +
+          "an index.html page to use as the pagination page. Skipping pagination.", "warn"
+        end
+      end # function run_compatability (REMOVE AFTER 2018-01-01)
+
+      # Returns the combination of all documents in the collections that are specified
+      # raw_collection_names can either be a list of collections separated by a ',' or ' ' or a single string
+      def get_docs_in_collections(raw_collection_names)
+        if raw_collection_names.is_a?(String)
+          collection_names = raw_collection_names.split(/;|,|\s/)
+        else
+          collection_names = raw_collection_names
+        end
+
+        docs = []
+        # Now for each of the collections get the docs
+        for coll_name in collection_names
+          # Request all the documents for the collection in question, and join it with the total collection 
+          docs += @collection_by_name_lambda.call(coll_name.downcase.strip)
+        end
+
+        return docs
+      end
+
+      def _fix_deprecated_config_features(config)
+        keys_to_delete = []
+
+        # As of v1.5.1 the title_suffix is deprecated and 'title' should be used 
+        # but only if title has not been defined already!
+        if( !config['title_suffix'].nil? )
+          if( config['title'].nil? )
+            config['title'] = ":title" + config['title_suffix'].to_s # Migrate the old key to title
+          end
+          keys_to_delete << "title_suffix" # Always remove the depricated key if found
+        end
+
+        # Delete the depricated keys
+        config.delete_if{ |k,| keys_to_delete.include? k }
+      end
+
+      def _debug_print_config_info(config, page_path)
+        r = 20
+        f = "Pagination: ".rjust(20)
+        # Debug print the config
+        if @debug
+          puts f + "----------------------------"
+          puts f + "Page: "+page_path.to_s
+          puts f + " Active configuration"
+          puts f + "  Enabled: ".ljust(r) + config['enabled'].to_s
+          puts f + "  Items per page: ".ljust(r) + config['per_page'].to_s
+          puts f + "  Permalink: ".ljust(r) + config['permalink'].to_s
+          puts f + "  Title: ".ljust(r) + config['title'].to_s
+          puts f + "  Limit: ".ljust(r) + config['limit'].to_s
+          puts f + "  Sort by: ".ljust(r) + config['sort_field'].to_s
+          puts f + "  Sort reverse: ".ljust(r) + config['sort_reverse'].to_s
+          
+          puts f + " Active Filters"
+          puts f + "  Collection: ".ljust(r) + config['collection'].to_s
+          puts f + "  Category: ".ljust(r) + (config['category'].nil? || config['category'] == "posts" ? "[Not set]" : config['category'].to_s)
+          puts f + "  Tag: ".ljust(r) + (config['tag'].nil? ? "[Not set]" : config['tag'].to_s)
+          puts f + "  Locale: ".ljust(r) + (config['locale'].nil? ? "[Not set]" : config['locale'].to_s)
+
+          if config['legacy'] 
+            puts f + " Legacy Paginate Code Enabled"
+            puts f + "  Legacy Paginate: ".ljust(r) + config['per_page'].to_s
+            puts f + "  Legacy Source: ".ljust(r) + config['legacy_source'].to_s
+            puts f + "  Legacy Path: ".ljust(r) + config['paginate_path'].to_s
+          end
+        end
+      end
+
+      def _debug_print_filtering_info(filter_name, before_count, after_count)
+        # Debug print the config
+        if @debug
+          puts "Pagination: ".rjust(20) + " Filtering by: "+filter_name.to_s.ljust(9) + " " + before_count.to_s.rjust(3) + " => " + after_count.to_s  
+        end
+      end
+      
+      #
+      # Rolls through all the pages passed in and finds all pages that have pagination enabled on them.
+      # These pages will be used as templates
+      #
+      # site_pages - All pages in the site
+      #
+      def discover_paginate_templates(site_pages)
+        candidates = []
+        site_pages.select do |page|
+          # If the page has the enabled config set, supports any type of file name html or md
+          if page.data['pagination'].is_a?(Hash) && page.data['pagination']['enabled']
+            candidates << page
+          end
+        end
+        return candidates
+      end # function discover_paginate_templates
+            
+      # 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.
+      #
+      # site - The Site.
+      # template - The index.html Page that requires pagination.
+      # config - The configuration settings that should be used
+      #
+      def paginate(template, config, site_title, all_posts, all_tags, all_categories, all_locales)
+        # By default paginate on all posts in the site
+        using_posts = all_posts
+        
+        # Now start filtering out any posts that the user doesn't want included in the pagination
+        before = using_posts.size.to_i
+        using_posts = PaginationIndexer.read_config_value_and_filter_posts(config, 'category', using_posts, all_categories)
+        self._debug_print_filtering_info('Category', before, using_posts.size.to_i)
+        before = using_posts.size.to_i
+        using_posts = PaginationIndexer.read_config_value_and_filter_posts(config, 'tag', using_posts, all_tags)
+        self._debug_print_filtering_info('Tag', before, using_posts.size.to_i)
+        before = using_posts.size.to_i
+        using_posts = PaginationIndexer.read_config_value_and_filter_posts(config, 'locale', using_posts, all_locales)
+        self._debug_print_filtering_info('Locale', before, using_posts.size.to_i)
+        
+        # Apply sorting to the posts if configured, any field for the post is available for sorting
+        if config['sort_field']
+          sort_field = config['sort_field'].to_s
+
+          # There is an issue in Jekyll related to lazy initialized member variables that causes iterators to 
+          # break when accessing an uninitialized value during iteration. This happens for document.rb when the <=> compaison function 
+          # is called (as this function calls the 'date' field which for drafts are not initialized.)
+          # So to unblock this common issue for the date field I simply iterate once over every document and initialize the .date field explicitly
+          if @debug
+            puts "Pagination: ".rjust(20) + "Rolling through the date fields for all documents"
+          end
+          for p in using_posts
+            tmp_date = p.date
+            if( !tmp_date || tmp_date.nil? )
+              if @debug
+                puts "Pagination: ".rjust(20) + "Explicitly assigning date for doc: #{p.data['title']} | #{p.path}"
+              end
+              p.date = File.mtime(p.path)
+            end
+          end
+
+          using_posts.sort!{ |a,b| Utils.sort_values(Utils.sort_get_post_data(a.data, sort_field), Utils.sort_get_post_data(b.data, sort_field)) }
+
+          if config['sort_reverse']
+            using_posts.reverse!
+          end
+        end
+               
+        # Calculate the max number of pagination-pages based on the configured per page value
+        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
+          total_pages = config['limit'].to_i
+        end
+
+        #### BEFORE STARTING REMOVE THE TEMPLATE PAGE FROM THE SITE LIST!
+        @page_remove_lambda.call( template )
+        
+        # list of all newly created pages
+        newpages = []
+
+        if total_pages == 0
+          total_pages = 1
+        end
+        # Now for each pagination page create it and configure the ranges for the collection
+        # This .pager member is a built in thing in Jekyll and defines the paginator implementation
+        # Simpy override to use mine
+        (1..total_pages).each do |cur_page_nr|
+
+          # 1. Create the in-memory page
+          #    External Proc call to create the actual page for us (this is passed in when the pagination is run)
+          newpage = PaginationPage.new( template, cur_page_nr, total_pages )
+
+          # 2. Create the url for the in-memory page (calc permalink etc), construct the title, set all page.data values needed
+          paginated_page_url = config['permalink']
+          first_index_page_url = ""
+          if template.data['permalink']
+            first_index_page_url = Utils.ensure_trailing_slash(template.data['permalink'])
+          else
+            first_index_page_url = Utils.ensure_trailing_slash(template.dir)
+          end
+          paginated_page_url = File.join(first_index_page_url, paginated_page_url)
+          
+          # 3. Create the pager logic for this page, pass in the prev and next page numbers, assign pager to in-memory page
+          newpage.pager = Paginator.new( config['per_page'], first_index_page_url, paginated_page_url, using_posts, cur_page_nr, total_pages)
+
+          # Create the url for the new page, make sure we prepend any permalinks that are defined in the template page before
+          if newpage.pager.page_path.end_with? '/'
+            newpage.set_url(File.join(newpage.pager.page_path, 'index.html'))
+          elsif newpage.pager.page_path.end_with? '.html'
+            # Support for direct .html files
+            newpage.set_url(newpage.pager.page_path)
+          else
+            # Support for extensionless permalinks
+            newpage.set_url(newpage.pager.page_path+'.html')
+          end
+
+          if( template.data['permalink'] )
+            newpage.data['permalink'] = newpage.pager.page_path
+          end
+
+          # Transfer the title across to the new page
+          if( !template.data['title'] )
+            tmp_title = site_title
+          else
+            tmp_title = template.data['title']
+          end
+          # If the user specified a title suffix to be added then let's add that to all the pages except the first
+          if( cur_page_nr > 1 && config.has_key?('title') )
+            newpage.data['title'] = "#{Utils.format_page_title(config['title'], tmp_title, cur_page_nr, total_pages)}"
+          else
+            newpage.data['title'] = tmp_title
+          end
+
+          # Signals that this page is automatically generated by the pagination logic
+          # (we don't do this for the first page as it is there to mask the one we removed)
+          if cur_page_nr > 1
+            newpage.data['autogen'] = "jekyll-paginate-v2-redux"
+          end
+          
+          # Add the page to the site
+          @page_add_lambda.call( newpage )
+
+          # Store the page in an internal list for later referencing if we need to generate a pagination number path later on
+          newpages << newpage
+        end #each.do total_pages
+
+        # Now generate the pagination number path, e.g. so that the users can have a prev 1 2 3 4 5 next structure on their page
+        # simplest is to include all of the links to the pages preceeding the current one
+        # (e.g for page 1 you get the list 2, 3, 4.... and for page 2 you get the list 3,4,5...)
+        if( config['trail'] && !config['trail'].nil? && newpages.size.to_i > 1 )
+          trail_before = [config['trail']['before'].to_i, 0].max
+          trail_after = [config['trail']['after'].to_i, 0].max
+          trail_length = trail_before + trail_after + 1
+
+          if( trail_before > 0 || trail_after > 0 )
+            newpages.select do | npage |
+              idx_start = [ npage.pager.page - trail_before - 1, 0].max # Selecting the beginning of the trail
+              idx_end = [idx_start + trail_length, newpages.size.to_i].min # Selecting the end of the trail
+
+              # Always attempt to maintain the max total of <trail_length> pages in the trail (it will look better if the trail doesn't shrink)
+              if( idx_end - idx_start < trail_length )
+                # Attempt to pad the beginning if we have enough pages
+                idx_start = [idx_start - ( trail_length - (idx_end - idx_start) ), 0].max # Never go beyond the zero index
+              end              
+
+              # Convert the newpages array into a two dimensional array that has [index, page_url] as items
+              #puts( "Trail created for page #{npage.pager.page} (idx_start:#{idx_start} idx_end:#{idx_end})")
+              npage.pager.page_trail = newpages[idx_start...idx_end].each_with_index.map {|ipage,idx| PageTrail.new(idx_start+idx+1, ipage.pager.page_path, ipage.data['title'])}
+              #puts( npage.pager.page_trail )
+            end #newpages.select
+          end #if trail_before / trail_after
+        end # if config['trail']
+
+      end # function paginate
+
+    end # class PaginationV2
+
+  end # module PaginateV2
+end # module Jekyll