j1_paginator 2019.1.0

data/README.md

@@ -0,0 +1,82 @@
+# Jekyll::Paginate V2
+
+Pagination gem built specially for Jekyll 3 and newer that is fully backwards compatible 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/j1_paginator).
+
+[![Code Shelter](https://www.codeshelter.co/static/badges/badge-flat.svg)](https://www.codeshelter.co/)
+[![Gem](https://img.shields.io/gem/v/j1_paginator.svg)](https://rubygems.org/gems/j1_paginator)
+[![Join the chat at https://gitter.im/j1_paginator/Lobby](https://badges.gitter.im/j1_paginator/Lobby.svg)](https://gitter.im/j1_paginator/Lobby)
+[![Build Status](https://travis-ci.org/sverrirs/j1_paginator.svg?branch=master)](https://travis-ci.org/sverrirs/j1_paginator) 
+[![Code Climate](https://codeclimate.com/github/sverrirs/j1_paginator/badges/gpa.svg)](https://codeclimate.com/github/sverrirs/j1_paginator)
+[![security](https://hakiri.io/github/sverrirs/j1_paginator/master.svg)](https://hakiri.io/github/sverrirs/j1_paginator/master)
+[![Gem](https://img.shields.io/gem/dt/j1_paginator.svg)](https://rubygems.org/gems/j1_paginator)
+
+Reach me at the [project issues](https://github.com/sverrirs/j1_paginator/issues) section or via email at [jekyll@sverrirs.com](mailto:jekyll@sverrirs.com), you can also get in touch on the project's [Gitter chat room](https://gitter.im/j1_paginator/Lobby).
+
+> 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/j1_paginator/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 j1_paginator
+```
+
+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/j1_paginator/tree/master/examples) for tips and tricks on how to configure the pagination logic.
+
+> :warning: Please note that this plugin is currently NOT supported by GitHub pages. Here is a [list of all plugins supported](https://pages.github.com/versions/). There is work underway to try to get it added it but until then please follow [this GitHub guide](https://help.github.com/articles/adding-jekyll-plugins-to-a-github-pages-site/) to enable it or use [Travis CI](https://ayastreb.me/deploy-jekyll-to-github-pages-with-travis-ci/). 
+
+> GitLab supposedly supports [any plugin](https://about.gitlab.com/comparison/gitlab-pages-vs-github-pages.html).
+
+
+## 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/j1_paginator/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 j1_paginator.gemspec`)
+6. Test and verify the gem locally (`gem install ./j1_paginator-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/j1_paginator/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/j1_paginator.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'j1_paginator/version'
+require 'date'
+
+Gem::Specification.new do |spec|
+  spec.name          = "j1_paginator"
+  spec.version       = Jekyll::J1Paginator::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/j1_paginator"
+  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"
+  spec.add_runtime_dependency "jekyll", '>= 3.0', '<= 4.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/j1_paginator.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/sverrirs/j1_paginator
+# Distributed Under The MIT License (MIT) as described in the LICENSE file
+#   - https://opensource.org/licenses/MIT
+
+require "j1_paginator/version"
+# Files needed for the pagination generator
+require "j1_paginator/generator/defaults"
+require "j1_paginator/generator/compatibilityUtils"
+require "j1_paginator/generator/utils"
+require "j1_paginator/generator/paginationIndexer"
+require "j1_paginator/generator/paginator"
+require "j1_paginator/generator/paginationPage"
+require "j1_paginator/generator/paginationModel"
+require "j1_paginator/generator/paginationGenerator"
+# Files needed for the auto category and tag pages
+require "j1_paginator/autopages/utils"
+require "j1_paginator/autopages/defaults"
+require "j1_paginator/autopages/autoPages"
+require "j1_paginator/autopages/pages/baseAutoPage"
+require "j1_paginator/autopages/pages/categoryAutoPage"
+require "j1_paginator/autopages/pages/collectionAutoPage"
+require "j1_paginator/autopages/pages/tagAutoPage"
+
+module Jekyll 
+  module J1Paginator
+  end # module J1Paginator
+end # module Jekyll

data/lib/j1_paginator/autopages/autoPages.rb

@@ -0,0 +1,77 @@
+module Jekyll
+  module J1Paginator::AutoPages
+
+    #
+    # This function is called right after the main generator is triggered by Jekyll
+    # This code is adapted from Stephen Crosby's code https://github.com/stevecrozz
+    def self.create_autopages(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::J1Paginator::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."
+        return
+      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 # create_autopages
+
+
+    # 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 J1Paginator
+end # module Jekyll

data/lib/j1_paginator/autopages/defaults.rb

@@ -0,0 +1,40 @@
+module Jekyll
+  module J1Paginator::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,
+        'slugify'       => {
+                              'mode' => 'none', # [raw default pretty ascii latin], none gives back the same string
+                              'cased'=> false # If cased is true, all uppercase letters in the result string are replaced with their lowercase counterparts.
+                            }
+      },
+      'categories'  => {
+        'layouts'       => ['autopage_category.html'],
+        'title'         => 'Posts in category :cat',
+        'permalink'     => '/category/:cat',
+        'enabled'       => true,
+        'slugify'       => {
+                              'mode' => 'none', # [raw default pretty ascii latin], none gives back the same string
+                              'cased'=> false # If cased is true, all uppercase letters in the result string are replaced with their lowercase counterparts.
+                            }
+      },
+      'collections' => {
+        'layouts'       => ['autopage_collection.html'],
+        'title'         => 'Posts in collection :coll',
+        'permalink'     => '/collection/:coll',
+        'enabled'       => true,
+        'slugify'       => {
+                              'mode' => 'none', # [raw default pretty ascii latin], none gives back the same string
+                              'cased'=> false # If cased is true, all uppercase letters in the result string are replaced with their lowercase counterparts.
+                            }
+      } 
+    }
+
+  end # module J1Paginator::AutoPages
+end # module Jekyll

data/lib/j1_paginator/autopages/pages/baseAutoPage.rb

@@ -0,0 +1,60 @@
+module Jekyll
+  module J1Paginator::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 J1Paginator
+end # module Jekyll

data/lib/j1_paginator/autopages/pages/categoryAutoPage.rb

@@ -0,0 +1,32 @@
+module Jekyll
+  module J1Paginator::AutoPages
+
+    class CategoryAutoPage < BaseAutoPage
+      def initialize(site, base, autopage_config, pagination_config, layout_name, category, category_name)
+
+        # Do we have a slugify configuration available
+        slugify_config = autopage_config.is_a?(Hash) && autopage_config.has_key?('slugify') ? autopage_config['slugify'] : nil
+
+        # 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
+          in_config['collection'] = site.collections.keys
+        end
+
+        get_autopage_permalink_lambda = lambda do |permalink_pattern|
+          return Utils.format_cat_macro(permalink_pattern, category, slugify_config)
+        end
+
+        get_autopage_title_lambda = lambda do |title_pattern|
+          return Utils.format_cat_macro(title_pattern, category, slugify_config)
+        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 J1Paginator
+end # module Jekyll

data/lib/j1_paginator/autopages/pages/collectionAutoPage.rb

@@ -0,0 +1,31 @@
+module Jekyll
+  module J1Paginator::AutoPages
+
+    class CollectionAutoPage < BaseAutoPage
+      def initialize(site, base, autopage_config, pagination_config, layout_name, collection, collection_name)
+
+        # Do we have a slugify configuration available
+        slugify_config = autopage_config.is_a?(Hash) && autopage_config.has_key?('slugify') ? autopage_config['slugify'] : nil
+
+        # 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, slugify_config)
+        end
+
+        get_autopage_title_lambda = lambda do |title_pattern|
+          return Utils.format_coll_macro(title_pattern, collection, slugify_config)
+        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 J1Paginator
+end # module Jekyll

data/lib/j1_paginator/autopages/pages/tagAutoPage.rb

@@ -0,0 +1,32 @@
+module Jekyll
+  module J1Paginator::AutoPages
+
+    class TagAutoPage < BaseAutoPage
+      def initialize(site, base, autopage_config, pagination_config, layout_name, tag, tag_name)
+
+        # Do we have a slugify configuration available
+        slugify_config = autopage_config.is_a?(Hash) && autopage_config.has_key?('slugify') ? autopage_config['slugify'] : nil
+
+        # 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
+          config['collection'] = site.collections.keys
+        end
+
+        get_autopage_permalink_lambda = lambda do |permalink_pattern|
+          return Utils.format_tag_macro(permalink_pattern, tag, slugify_config)
+        end
+
+        get_autopage_title_lambda = lambda do |title_pattern|
+          return Utils.format_tag_macro(title_pattern, tag, slugify_config)
+        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 J1Paginator
+end # module Jekyll