bridgetown-paginate 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7af8a59db674148dbfbb66a2ade0333ceb589917f22eef04533cde1cd097d65d
+  data.tar.gz: e75a96fc01a65161609c90923a222883dfcf500102dc9f36d7924468545fc04f
+SHA512:
+  metadata.gz: b261fecd3cbae9ac8e8f0dfd3e5232e1fc516cd6a667cba3467e23152109d3e5a07364cfee7f694b36cd35f524532f0a01db79415649a9e999faa67c3aceb81a
+  data.tar.gz: 2a1d1d909a289a7f0578792b11b9eb2d1b2fc30d6cf39de4c52313f0d7eb4237fc8540ad23d994820f3d9fc03355222344bdc5c397cf1ccd3b5657b875d9606b

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,52 @@
+---
+inherit_from: ../.rubocop.yml
+
+AllCops:
+  Include:
+    - lib/**/*.rb
+    - spec/**/*.rb
+
+Bridgetown/NoPutsAllowed:
+  Exclude:
+    - lib/bridgetown-paginate/pagination_model.rb
+Layout/CommentIndentation:
+  Exclude:
+    - lib/bridgetown-paginate/defaults.rb
+Metrics/AbcSize:
+  Exclude:
+    - lib/bridgetown-paginate/pagination_generator.rb
+    - lib/bridgetown-paginate/pagination_indexer.rb
+    - lib/bridgetown-paginate/pagination_model.rb
+    - lib/bridgetown-paginate/pagination_page.rb
+    - lib/bridgetown-paginate/paginator.rb
+Metrics/BlockNesting:
+  Exclude:
+    - lib/bridgetown-paginate/pagination_model.rb
+Metrics/ClassLength:
+  Exclude:
+    - lib/bridgetown-paginate/pagination_model.rb
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - lib/bridgetown-paginate/pagination_generator.rb
+    - lib/bridgetown-paginate/pagination_indexer.rb
+    - lib/bridgetown-paginate/pagination_model.rb
+    - lib/bridgetown-paginate/paginator.rb
+Metrics/MethodLength:
+  Exclude:
+    - lib/bridgetown-paginate/pagination_generator.rb
+    - lib/bridgetown-paginate/pagination_indexer.rb
+    - lib/bridgetown-paginate/pagination_model.rb
+    - lib/bridgetown-paginate/paginator.rb
+Metrics/ParameterLists:
+  Exclude:
+    - lib/bridgetown-paginate/pagination_model.rb
+    - lib/bridgetown-paginate/paginator.rb
+Metrics/PerceivedComplexity:
+  Exclude:
+    - lib/bridgetown-paginate/pagination_generator.rb
+    - lib/bridgetown-paginate/pagination_indexer.rb
+    - lib/bridgetown-paginate/pagination_model.rb
+    - lib/bridgetown-paginate/paginator.rb
+Style/Next:
+  Exclude:
+    - lib/bridgetown-paginate/pagination_model.rb

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"

data/bridgetown-paginate.gemspec

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../bridgetown-core/lib/bridgetown-core/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "bridgetown-paginate"
+  spec.version       = Bridgetown::VERSION
+  spec.author        = "Bridgetown Team"
+  spec.email         = "maintainers@bridgetownrb.com"
+  spec.summary       = "A Bridgetown plugin to add pagination support for posts and collection indices."
+  spec.homepage      = "https://github.com/bridgetownrb/bridgetown-paginate"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r!^(test|script|spec|features)/!) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency("bridgetown-core", Bridgetown::VERSION)
+end

data/lib/bridgetown-paginate.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#################################################
+# Special thanks to Sverrir Sigmundarson and the
+# contributors to Jekyll::Paginate V2 for the
+# basis of this gem.
+# https://github.com/sverrirs/jekyll-paginate-v2
+#################################################
+
+require "bridgetown-core"
+require "bridgetown-core/version"
+
+unless ENV["BRIDGETOWN_DISABLE_PAGINATE_GEM"] == "true"
+  module Bridgetown
+    module Paginate
+    end
+  end
+
+  require "bridgetown-paginate/defaults"
+  require "bridgetown-paginate/utils"
+  require "bridgetown-paginate/pagination_indexer"
+  require "bridgetown-paginate/paginator"
+  require "bridgetown-paginate/pagination_page"
+  require "bridgetown-paginate/pagination_model"
+  require "bridgetown-paginate/pagination_generator"
+end

data/lib/bridgetown-paginate/defaults.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Paginate
+    module Generator
+      # The default configuration for the Paginator
+      DEFAULT = {
+        "enabled"      => false,
+        "collection"   => "posts",
+        "offset"       => 0, # Supports skipping x number of posts from the
+                             # beginning of the post list
+        "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)
+        },
+        "indexpage"    => nil, # The default name of the index pages
+        "extension"    => "html", # The default extension for the output pages
+                                  # (ignored if indexpage is nil)
+        "debug"        => false, # Turns on debug output for the gem
+      }.freeze
+    end
+  end
+end

data/lib/bridgetown-paginate/pagination_generator.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Paginate
+    module Generator
+      #
+      # The main entry point into the generator, called by Bridgetown
+      # this function extracts all the necessary information from the Bridgetown
+      # 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 < Bridgetown::Generator
+        # 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)
+          # Retrieve and merge the pagination configuration from the site yml file
+          default_config = Bridgetown::Utils.deep_merge_hashes(
+            DEFAULT,
+            site.config["pagination"] || {}
+          )
+
+          # If disabled then simply quit
+          unless default_config["enabled"]
+            Bridgetown.logger.info "Pagination:", "Disabled in site.config."
+            return
+          end
+
+          Bridgetown.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.data.dig("metadata", "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 Bridgetown 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
+              site.collections.each do |coll_name, coll_data|
+                next unless !coll_data.nil? && coll_name != "posts"
+
+                # Exclude all pagination pages
+                coll += coll_data.docs.reject do |doc|
+                  doc.data.key?("pagination")
+                end
+              end
+            else
+              # Just the one collection requested
+              return [] unless site.collections.key?(collection_name)
+
+              # Exclude all pagination pages
+              coll = site.collections[collection_name].docs.reject do |doc|
+                doc.data.key?("pagination")
+              end
+            end
+            return coll
+          end
+
+          ################ 2 ####################
+          # Create the proc that constructs the real-life site page
+          # This is necessary to decouple the code from the Bridgetown 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 Bridgetown specific logging
+          logging_lambda = lambda do |message, type = "info"|
+            if type == "debug"
+              Bridgetown.logger.debug "Pagination:", message.to_s
+            elsif type == "error"
+              Bridgetown.logger.error "Pagination:", message.to_s
+            elsif type == "warn"
+              Bridgetown.logger.warn "Pagination:", message.to_s
+            else
+              Bridgetown.logger.info "Pagination:", message.to_s
+            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
+          )
+          count = model.run(default_config, all_pages, site_title)
+          Bridgetown.logger.info "Pagination:", "Complete, processed #{count} pagination page(s)"
+        end
+      end
+    end
+  end
+end

data/lib/bridgetown-paginate/pagination_indexer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Paginate
+    module 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 documents based on a key in the
+        # document.data table
+        #
+        def self.index_documents_by(all_documents, index_key)
+          return nil if all_documents.nil?
+          return all_documents if index_key.nil?
+
+          index = {}
+          all_documents.each do |document|
+            next if document.data.nil?
+            next unless document.data.key?(index_key)
+            next if document.data[index_key].nil?
+            next if document.data[index_key].size <= 0
+            next if document.data[index_key].to_s.strip.empty?
+
+            # Only tags and categories come as premade arrays, locale does not,
+            # so convert any data elements that are strings into arrays
+            document_data = document.data[index_key]
+            document_data = document_data.split(%r!;|,|\s!) if document_data.is_a?(String)
+
+            document_data.each do |key|
+              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)
+              key.split(%r!;|,!).each do |k_split|
+                k_split = k_split.to_s.downcase.strip # Clean whitespace and junk
+                index[k_split.to_s] = [] unless index.key?(k_split)
+                index[k_split.to_s] << document
+              end
+            end
+          end
+
+          index
+        end
+
+        #
+        # 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 &= item
+          end
+
+          intersect
+        end
+
+        # Filters documents based on a keyed source_documents hash of indexed
+        # documents and performs a intersection of the two sets. Returns only
+        # documents that are common between all collections
+        def self.read_config_value_and_filter_documents(
+          config,
+          config_key,
+          documents,
+          source_documents
+        )
+          return nil if documents.nil?
+
+          # If the source is empty then simply don't do anything
+          return nil if source_documents.nil?
+
+          return documents if config.nil?
+          return documents unless config.key?(config_key)
+          return documents 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
+          config_value = config_value.split(%r!;|,!) if config_value.is_a?(String)
+
+          # Now for all filter values for the config key, let's remove all items
+          # from the documents that aren't common for all collections that the
+          # user wants to filter on
+          config_value.each do |key|
+            key = key.to_s.downcase.strip
+            documents = PaginationIndexer.intersect_arrays(documents, source_documents[key])
+          end
+
+          # The fully filtered final document list
+          documents
+        end
+      end
+    end
+  end
+end

data/lib/bridgetown-paginate/pagination_model.rb

@@ -0,0 +1,419 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Paginate
+    module 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?
+        # The lambda to use for logging
+        @logging_lambda = nil
+        # The lambda used to create pages and add them to the site
+        @page_add_lambda = nil
+        # Lambda to remove a page from the site.pages collection
+        @page_remove_lambda = nil
+        # Lambda to get all documents/posts in a particular collection (by name)
+        @collection_by_name_lambda = nil
+
+        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 = 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
+          templates.each do |template|
+            # All pages that should be paginated need to include the pagination
+            # config element
+            if template.data["pagination"].is_a?(Hash)
+              template_config = Bridgetown::Utils.deep_merge_hashes(
+                default_config,
+                template.data["pagination"] || {}
+              )
+
+              # Is debugging enabled on the page level
+              @debug = template_config["debug"]
+
+              _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"]
+                @logging_lambda.call "found page: " + template.path, "debug" unless @debug
+
+                # Request all documents in all collections that the user has requested
+                all_posts = get_docs_in_collections(template_config["collection"])
+
+                # Create the necessary indexes for the posts
+                all_categories = PaginationIndexer.index_documents_by(all_posts, "categories")
+                all_tags = PaginationIndexer.index_documents_by(all_posts, "tags")
+                all_locales = PaginationIndexer.index_documents_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
+                paginate(
+                  template,
+                  template_config,
+                  site_title,
+                  all_posts,
+                  all_tags,
+                  all_categories,
+                  all_locales
+                )
+              end
+            end
+          end
+
+          # Return the total number of templates found
+          templates.size.to_i
+        end
+
+        # 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)
+          collection_names = if raw_collection_names.is_a?(String)
+                               raw_collection_names.split %r!/;|,|\s/!
+                             else
+                               raw_collection_names
+                             end
+
+          docs = []
+          # Now for each of the collections get the docs
+          collection_names.each do |coll_name|
+            # 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
+
+          # Hidden documents should not not be processed anywhere.
+          docs = docs.reject { |doc| doc["hidden"] }
+
+          docs
+        end
+
+        # rubocop:disable Layout/LineLength
+        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 + "  Offset: ".ljust(r) + config["offset"].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)
+          end
+        end
+        # rubocop:enable Layout/LineLength
+
+        # rubocop:disable Layout/LineLength
+        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
+        # rubocop:enable Layout/LineLength
+
+        #
+        # 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)
+          site_pages.select do |page|
+            page.data["pagination"].is_a?(Hash) && page.data["pagination"]["enabled"]
+          end
+        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.
+        #
+        # 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_documents(
+            config,
+            "category",
+            using_posts,
+            all_categories
+          )
+          _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_documents(
+            config,
+            "tag",
+            using_posts,
+            all_tags
+          )
+          _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_documents(
+            config,
+            "locale",
+            using_posts,
+            all_locales
+          )
+          _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 Bridgetown 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 <=> comparison 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
+            using_posts.each do |u_post|
+              next unless u_post.respond_to?("date")
+
+              tmp_date = u_post.date
+              if !tmp_date || tmp_date.nil?
+                if @debug
+                  puts "Pagination: ".rjust(20) +
+                    "Explicitly assigning date for doc: #{u_post.data["title"]} | #{u_post.path}"
+                end
+                u_post.date = File.mtime(u_post.path)
+              end
+            end
+
+            using_posts.sort! do |a, b|
+              Utils.sort_values(
+                Utils.sort_get_post_data(a.data, sort_field),
+                Utils.sort_get_post_data(b.data, sort_field)
+              )
+            end
+
+            # Remove the first x entries
+            offset_post_count = [0, config["offset"].to_i].max
+            using_posts.pop(offset_post_count)
+
+            using_posts.reverse! if config["sort_reverse"]
+          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"].to_i.positive? && 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 = []
+
+          # Consider the default index page name and extension
+          index_page_name = if config["indexpage"].nil?
+                              ""
+                            else
+                              config["indexpage"].split(".")[0]
+                            end
+          index_page_ext = if config["extension"].nil?
+                             ""
+                           else
+                             Utils.ensure_leading_dot(config["extension"])
+                           end
+          index_page_with_ext = index_page_name + index_page_ext
+
+          # In case there are no (visible) posts, generate the index file anyway
+          total_pages = 1 if total_pages.zero?
+
+          # Now for each pagination page create it and configure the ranges for
+          # the collection
+          # The .pager member is a built in thing in Bridgetown and references the
+          # paginator implementation
+          # rubocop:disable Metrics/BlockLength
+          (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, index_page_with_ext
+
+            # 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"]
+                                     Utils.ensure_trailing_slash(
+                                       template.data["permalink"]
+                                     )
+                                   else
+                                     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,
+              index_page_name,
+              index_page_ext
+            )
+
+            # 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_page_with_ext))
+            elsif newpage.pager.page_path.end_with? index_page_ext
+              # Support for direct .html files
+              newpage.set_url(newpage.pager.page_path)
+            else
+              # Support for extensionless permalinks
+              newpage.set_url(newpage.pager.page_path + index_page_ext)
+            end
+
+            newpage.data["permalink"] = newpage.pager.page_path if template.data["permalink"]
+
+            # Transfer the title across to the new page
+            tmp_title = if !template.data["title"]
+                          site_title
+                        else
+                          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.key?("title")
+              newtitle = Utils.format_page_title(
+                config["title"],
+                tmp_title,
+                cur_page_nr,
+                total_pages
+              )
+              newpage.data["title"] = newtitle.to_s
+            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)
+            newpage.data["autogen"] = "bridgetown-paginate" if cur_page_nr > 1
+
+            # 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
+          # rubocop:enable Metrics/BlockLength
+
+          # 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.positive?
+            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.positive? || trail_after.positive?
+              newpages.select do |npage|
+                # Selecting the beginning of the trail
+                idx_start = [npage.pager.page - trail_before - 1, 0].max
+                # Selecting the end of the trail
+                idx_end = [idx_start + trail_length, newpages.size.to_i].min
+
+                # 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
+                  # Never go beyond the zero index
+                  idx_start = [
+                    idx_start - (trail_length - (idx_end - idx_start)),
+                    0,
+                  ].max
+                end
+
+                # Convert the newpages array into a two dimensional array that has
+                # [index, page_url] as items
+                npage.pager.page_trail = newpages[idx_start...idx_end] \
+                  .each_with_index.map do |ipage, idx|
+                  PageTrail.new(
+                    idx_start + idx + 1,
+                    ipage.pager.page_path,
+                    ipage.data["title"]
+                  )
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bridgetown-paginate/pagination_page.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Paginate
+    module Generator
+      #
+      # This page handles the creation of the fake pagination pages based on the
+      # original page configuration.
+      # The code does the same things as the default Bridgetown page.rb code but
+      # just forces the code to look into the template instead of the (currently
+      # non-existing) pagination page. This page exists purely in memory and is
+      # not read from disk
+      #
+      class PaginationPage < Bridgetown::Page
+        def initialize(page_to_copy, cur_page_nr, total_pages, index_pageandext)
+          @site = page_to_copy.site
+          @base = ""
+          @url = ""
+          @name = index_pageandext.nil? ? "index.html" : index_pageandext
+          @path = page_to_copy.path
+
+          # Creates the basename and ext member values
+          process(@name)
+
+          # Only need to copy the data part of the page as it already contains the
+          # layout information
+          self.data = Bridgetown::Utils.deep_merge_hashes page_to_copy.data, {}
+          if !page_to_copy.data["autopage"]
+            self.content = page_to_copy.content
+          elsif page_to_copy.data["autopage"].key?("display_name")
+            # If the page is an auto page then migrate the necessary autopage info
+            # across into the new pagination page (so that users can get the
+            # correct keys etc)
+            data["autopages"] = Bridgetown::Utils.deep_merge_hashes(
+              page_to_copy.data["autopage"], {}
+            )
+          end
+
+          # Store the current page and total page numbers in the pagination_info construct
+          data["pagination_info"] = { "curr_page" => cur_page_nr, "total_pages" => total_pages }
+
+          # Perform some validation that is also performed in Bridgetown::Page
+          validate_data! page_to_copy.path
+          validate_permalink! page_to_copy.path
+
+          # TODO: Trigger a page event
+          # Bridgetown::Hooks.trigger :pages, :post_init, self
+        end
+
+        # rubocop:disable Naming/AccessorMethodName
+        def set_url(url_value)
+          @path = url_value.delete_prefix "/"
+          @dir  = File.dirname(@path)
+          @url = url_value
+        end
+        # rubocop:enable Naming/AccessorMethodName
+      end
+    end
+  end
+end

data/lib/bridgetown-paginate/paginator.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Paginate
+    module Generator
+      #
+      # Handles the preparation of all the documents based on the current page index
+      #
+      class Paginator
+        attr_reader :page, :per_page, :documents, :total_documents, :total_pages,
+                    :previous_page, :previous_page_path, :next_page, :next_page_path, :page_path,
+                    :first_page, :first_page_path, :last_page, :last_page_path
+        attr_accessor :page_trail
+
+        # Initialize a new Paginator.
+        #
+        def initialize(
+          config_per_page,
+          first_index_page_url,
+          paginated_page_url,
+          documents,
+          cur_page_nr,
+          num_pages,
+          default_indexpage,
+          default_ext
+        )
+          @page = cur_page_nr
+          @per_page = config_per_page.to_i
+          @total_pages = num_pages
+
+          if @page > @total_pages
+            raise "page number can't be greater than total pages:" \
+              " #{@page} > #{@total_pages}"
+          end
+
+          init = (@page - 1) * @per_page
+          offset = if init + @per_page - 1 >= documents.size
+                     documents.size
+                   else
+                     init + @per_page - 1
+                   end
+
+          # Ensure that the current page has correct extensions if needed
+          this_page_url = Utils.ensure_full_path(
+            @page == 1 ? first_index_page_url : paginated_page_url,
+            !default_indexpage || default_indexpage.empty? ? "index" : default_indexpage,
+            !default_ext || default_ext.empty? ? ".html" : default_ext
+          )
+
+          # To support customizable pagination pages we attempt to explicitly
+          # append the page name to the url incase the user is using extensionless permalinks.
+          if default_indexpage&.length&.positive?
+            # Adjust first page url
+            first_index_page_url = Utils.ensure_full_path(
+              first_index_page_url, default_indexpage, default_ext
+            )
+            # Adjust the paginated pages as well
+            paginated_page_url = Utils.ensure_full_path(
+              paginated_page_url, default_indexpage, default_ext
+            )
+          end
+
+          @total_documents = documents.size
+          @documents = documents[init..offset]
+          @page_path = Utils.format_page_number(this_page_url, cur_page_nr, @total_pages)
+
+          @previous_page = @page != 1 ? @page - 1 : nil
+          @previous_page_path = unless @page == 1
+                                  if @page == 2
+                                    Utils.format_page_number(
+                                      first_index_page_url, 1, @total_pages
+                                    )
+                                  else
+                                    Utils.format_page_number(
+                                      paginated_page_url,
+                                      @previous_page,
+                                      @total_pages
+                                    )
+                                  end
+                                end
+          @next_page = @page != @total_pages ? @page + 1 : nil
+          @next_page_path = if @page != @total_pages
+                              Utils.format_page_number(
+                                paginated_page_url, @next_page, @total_pages
+                              )
+                            end
+
+          @first_page = 1
+          @first_page_path = Utils.format_page_number(first_index_page_url, 1, @total_pages)
+          @last_page = @total_pages
+          @last_page_path = Utils.format_page_number(paginated_page_url, @total_pages, @total_pages)
+        end
+
+        # Convert this Paginator's data to a Hash suitable for use by Liquid.
+        #
+        # Returns the Hash representation of this Paginator.
+        def to_liquid
+          {
+            "per_page"           => per_page,
+            "documents"          => documents,
+            "total_documents"    => total_documents,
+            "total_pages"        => total_pages,
+            "page"               => page,
+            "page_path"          => page_path,
+            "previous_page"      => previous_page,
+            "previous_page_path" => previous_page_path,
+            "next_page"          => next_page,
+            "next_page_path"     => next_page_path,
+            "first_page"         => first_page,
+            "first_page_path"    => first_page_path,
+            "last_page"          => last_page,
+            "last_page_path"     => last_page_path,
+            "page_trail"         => page_trail,
+          }
+        end
+      end
+
+      # Small utility class that handles individual pagination trails
+      # and makes them easier to work with in Liquid
+      class PageTrail
+        attr_reader :num, :path, :title
+
+        def initialize(num, path, title)
+          @num = num
+          @path = path
+          @title = title
+        end
+
+        def to_liquid
+          {
+            "num"   => num,
+            "path"  => path,
+            "title" => title,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/bridgetown-paginate/utils.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Paginate
+    module Generator
+      # Static utility functions that are used in the code and
+      # don't belong in once place in particular
+      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: returns a fully formatted string with the current (:num) page
+        # number and maximum (:max) page count replaced if configured
+        #
+        def self.format_page_number(to_format, cur_page_nr, total_page_count = nil)
+          s = to_format.sub(":num", cur_page_nr.to_s)
+          s = s.sub(":max", total_page_count.to_s) unless total_page_count.nil?
+
+          s
+        end
+
+        # Static: returns a fully formatted string with the :title variable and
+        # the current (:num) page number and maximum (:max) page count replaced
+        #
+        def self.format_page_title(to_format, title, cur_page_nr = nil, total_page_count = nil)
+          format_page_number(to_format.sub(":title", title.to_s), cur_page_nr, total_page_count)
+        end
+
+        # Static: Return a String version of the input which has a leading dot.
+        #         If the input already has a dot in position zero, it will be
+        #         returned unchanged.
+        #
+        # path - a String path
+        #
+        # Returns the path with a leading slash
+        def self.ensure_leading_dot(path)
+          path[0..0] == "." ? path : ".#{path}"
+        end
+
+        # Static: Return a String version of the input which has a leading slash.
+        #         If the input already has a forward slash in position zero, it will be
+        #         returned unchanged.
+        #
+        # path - a String path
+        #
+        # Returns the path with a leading slash
+        def self.ensure_leading_slash(path)
+          path[0..0] == "/" ? path : "/#{path}"
+        end
+
+        # Static: Return a String version of the input without a leading slash.
+        #
+        # path - a String path
+        #
+        # Returns the input without the leading slash
+        def self.remove_leading_slash(path)
+          path[0..0] == "/" ? path[1..-1] : path
+        end
+
+        # Static: Return a String version of the input which has a trailing slash.
+        #         If the input already has a forward slash at the end, it will be
+        #         returned unchanged.
+        #
+        # path - a String path
+        #
+        # Returns the path with a trailing slash
+        def self.ensure_trailing_slash(path)
+          path[-1] == "/" ? path : "#{path}/"
+        end
+
+        #
+        # Sorting routine used for ordering posts by custom fields.
+        # Handles Strings separately as we want a case-insenstive sorting
+        #
+        # rubocop:disable Naming/MethodParameterName, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def self.sort_values(a, b)
+          if a.nil? && !b.nil?
+            return -1
+          elsif !a.nil? && b.nil?
+            return 1
+          end
+
+          return a.downcase <=> b.downcase if a.is_a?(String)
+
+          if a.respond_to?("to_datetime") && b.respond_to?("to_datetime")
+            return a.to_datetime <=> b.to_datetime
+          end
+
+          # By default use the built in sorting for the data type
+          a <=> b
+        end
+        # rubocop:enable Naming/MethodParameterName, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+        # Retrieves the given sort field from the given post
+        # the sort_field variable can be a hierarchical value on the form
+        # "parent_field:child_field" repeated as many times as needed
+        # only the leaf child_field will be retrieved
+        def self.sort_get_post_data(post_data, sort_field)
+          # Begin by splitting up the sort_field by (;,:.)
+          sort_split = sort_field.split(":")
+          sort_value = post_data
+
+          sort_split.each do |r_key|
+            key = r_key.downcase.strip # Remove any erronious whitespace and convert to lower case
+            return nil unless sort_value.key?(key)
+
+            # Work my way through the hash
+            sort_value = sort_value[key]
+          end
+
+          # If the sort value is a hash then return nil else return the value
+          if sort_value.is_a?(Hash)
+            nil
+          else
+            sort_value
+          end
+        end
+
+        # Ensures that the passed in url has a index and extension applied
+        def self.ensure_full_path(url, default_index, default_ext)
+          if url.end_with?("/")
+            url + default_index + default_ext
+          elsif !url.include?(".")
+            url + default_index
+          else
+            url
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: bridgetown-paginate
+version: !ruby/object:Gem::Version
+  version: 0.8.0
+platform: ruby
+authors:
+- Bridgetown Team
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-04-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bridgetown-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+description: 
+email: maintainers@bridgetownrb.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- Rakefile
+- bridgetown-paginate.gemspec
+- lib/bridgetown-paginate.rb
+- lib/bridgetown-paginate/defaults.rb
+- lib/bridgetown-paginate/pagination_generator.rb
+- lib/bridgetown-paginate/pagination_indexer.rb
+- lib/bridgetown-paginate/pagination_model.rb
+- lib/bridgetown-paginate/pagination_page.rb
+- lib/bridgetown-paginate/paginator.rb
+- lib/bridgetown-paginate/utils.rb
+homepage: https://github.com/bridgetownrb/bridgetown-paginate
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.6
+signing_key: 
+specification_version: 4
+summary: A Bridgetown plugin to add pagination support for posts and collection indices.
+test_files: []