j1_paginator 2019.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,82 @@
1
+ # Jekyll::Paginate V2
2
+
3
+ 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).
4
+
5
+ [![Code Shelter](https://www.codeshelter.co/static/badges/badge-flat.svg)](https://www.codeshelter.co/)
6
+ [![Gem](https://img.shields.io/gem/v/j1_paginator.svg)](https://rubygems.org/gems/j1_paginator)
7
+ [![Join the chat at https://gitter.im/j1_paginator/Lobby](https://badges.gitter.im/j1_paginator/Lobby.svg)](https://gitter.im/j1_paginator/Lobby)
8
+ [![Build Status](https://travis-ci.org/sverrirs/j1_paginator.svg?branch=master)](https://travis-ci.org/sverrirs/j1_paginator)
9
+ [![Code Climate](https://codeclimate.com/github/sverrirs/j1_paginator/badges/gpa.svg)](https://codeclimate.com/github/sverrirs/j1_paginator)
10
+ [![security](https://hakiri.io/github/sverrirs/j1_paginator/master.svg)](https://hakiri.io/github/sverrirs/j1_paginator/master)
11
+ [![Gem](https://img.shields.io/gem/dt/j1_paginator.svg)](https://rubygems.org/gems/j1_paginator)
12
+
13
+ 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).
14
+
15
+ > 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)).
16
+
17
+ * [Installation](#installation)
18
+ * [Example Sites](https://github.com/sverrirs/j1_paginator/tree/master/examples)
19
+ * [Pagination Generator](#pagination-generator)
20
+ * [Auto-Pages](#auto-pages)
21
+ * [Issues / to-be-completed](#issues--to-be-completed)
22
+ * [How to Contribute](#contributing)
23
+
24
+ > _"Be excellent to each other"_
25
+
26
+ :heart:
27
+
28
+ ## Installation
29
+
30
+ ```
31
+ gem install j1_paginator
32
+ ```
33
+
34
+ Update your [_config.yml](README-GENERATOR.md#site-configuration) and [pages](README-GENERATOR.md#page-configuration).
35
+
36
+ > 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).
37
+
38
+ Now you're ready to run `jekyll serve` and your paginated files should be generated.
39
+
40
+ Please see the [Examples](https://github.com/sverrirs/j1_paginator/tree/master/examples) for tips and tricks on how to configure the pagination logic.
41
+
42
+ > :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/).
43
+
44
+ > GitLab supposedly supports [any plugin](https://about.gitlab.com/comparison/gitlab-pages-vs-github-pages.html).
45
+
46
+
47
+ ## Pagination Generator
48
+
49
+ The [Pagination Generator](README-GENERATOR.md) forms the core of the pagination logic. Calculates and generates the pagination pages.
50
+
51
+
52
+ ## Auto Pages
53
+
54
+ The [Auto-Pages](README-AUTOPAGES.md) is an optional feature that auto-magically generates paginated pages for all your tags, categories and collections.
55
+
56
+
57
+ ## Issues / to-be-completed
58
+
59
+ * Unit-tests do not cover all critical code paths
60
+ * No integration tests yet [#2](https://github.com/jekyll/jekyll-paginate/pull/2)
61
+ * _Exclude_ filter not implemented [#6](https://github.com/jekyll/jekyll-paginate/issues/6)
62
+ * Elegant way of collecting and printing debug information during pagination
63
+
64
+
65
+ I welcome all testers and people willing to give me feedback and code reviews.
66
+
67
+ ## Contributing
68
+
69
+ > 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.
70
+
71
+ 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).
72
+
73
+ 1. Fork it ( https://github.com/sverrirs/j1_paginator/fork )
74
+ 2. Create your feature branch (`git checkout -b my-new-feature`)
75
+ 3. Run the unit tests (`rake`)
76
+ 4. Commit your changes (`git commit -am 'Add some feature'`)
77
+ 5. Build the gem locally (`gem build j1_paginator.gemspec`)
78
+ 6. Test and verify the gem locally (`gem install ./j1_paginator-x.x.x.gem`)
79
+ 7. Push to the branch (`git push origin my-new-feature`)
80
+ 8. Create new Pull Request
81
+
82
+ Note: This project uses [semantic versioning](http://semver.org/).
@@ -0,0 +1,16 @@
1
+ require 'rake'
2
+ require 'rake/testtask'
3
+
4
+ #$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), *%w[lib]))
5
+ #require 'lib/j1_paginator/version'
6
+
7
+ Rake::TestTask.new do |t|
8
+ t.libs.push 'lib'
9
+ t.libs.push 'specs'
10
+ t.verbose = true
11
+ t.pattern = "spec/**/*_spec.rb"
12
+ t.test_files = FileList['spec/**/*_spec.rb']
13
+ end
14
+
15
+ desc "Run tests"
16
+ task :default => [:test]
@@ -0,0 +1,34 @@
1
+ # coding: utf-8
2
+ lib = File.expand_path('../lib', __FILE__)
3
+ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
4
+ require 'j1_paginator/version'
5
+ require 'date'
6
+
7
+ Gem::Specification.new do |spec|
8
+ spec.name = "j1_paginator"
9
+ spec.version = Jekyll::J1Paginator::VERSION
10
+ spec.platform = Gem::Platform::RUBY
11
+ spec.required_ruby_version = '>= 2.0.0' # Same as Jekyll
12
+ spec.date = DateTime.now.strftime('%Y-%m-%d')
13
+ spec.authors = ["Sverrir Sigmundarson"]
14
+ spec.email = ["jekyll@sverrirs.com"]
15
+ spec.homepage = "https://github.com/sverrirs/j1_paginator"
16
+ spec.license = "MIT"
17
+
18
+ spec.summary = %q{Pagination Generator for Jekyll 3}
19
+ 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.}
20
+
21
+ spec.files = Dir['CODE_OF_CONDUCT.md', 'README*.md', 'LICENSE', 'Rakefile', '*.gemspec', 'Gemfile', 'lib/**/*', 'spec/**/*']
22
+ spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
23
+ spec.require_paths = ["lib"]
24
+
25
+ # Gem requires Jekyll to work
26
+ # ~> is the pessimistic operator and is equivalent to '>= 3.0', '< 4.0'
27
+ #spec.add_runtime_dependency "jekyll", "~> 3.0"
28
+ spec.add_runtime_dependency "jekyll", '>= 3.0', '<= 4.0'
29
+
30
+ # Development requires more
31
+ spec.add_development_dependency "bundler", "~> 1.5"
32
+ spec.add_development_dependency "rake", "~> 10.4"
33
+ spec.add_development_dependency "minitest", '~> 5.4'
34
+ end
@@ -0,0 +1,34 @@
1
+ # Jekyll::Paginate V2 is a gem built for Jekyll 3 that generates pagiatation for posts, collections, categories and tags.
2
+ #
3
+ # It is based on https://github.com/jekyll/jekyll-paginate, the original Jekyll paginator
4
+ # which was decommissioned in Jekyll 3 release onwards. This code is currently not officially
5
+ # supported on Jekyll versions < 3.0 (although it might work)
6
+ #
7
+ # Author: Sverrir Sigmundarson
8
+ # Site: https://github.com/sverrirs/j1_paginator
9
+ # Distributed Under The MIT License (MIT) as described in the LICENSE file
10
+ # - https://opensource.org/licenses/MIT
11
+
12
+ require "j1_paginator/version"
13
+ # Files needed for the pagination generator
14
+ require "j1_paginator/generator/defaults"
15
+ require "j1_paginator/generator/compatibilityUtils"
16
+ require "j1_paginator/generator/utils"
17
+ require "j1_paginator/generator/paginationIndexer"
18
+ require "j1_paginator/generator/paginator"
19
+ require "j1_paginator/generator/paginationPage"
20
+ require "j1_paginator/generator/paginationModel"
21
+ require "j1_paginator/generator/paginationGenerator"
22
+ # Files needed for the auto category and tag pages
23
+ require "j1_paginator/autopages/utils"
24
+ require "j1_paginator/autopages/defaults"
25
+ require "j1_paginator/autopages/autoPages"
26
+ require "j1_paginator/autopages/pages/baseAutoPage"
27
+ require "j1_paginator/autopages/pages/categoryAutoPage"
28
+ require "j1_paginator/autopages/pages/collectionAutoPage"
29
+ require "j1_paginator/autopages/pages/tagAutoPage"
30
+
31
+ module Jekyll
32
+ module J1Paginator
33
+ end # module J1Paginator
34
+ end # module Jekyll
@@ -0,0 +1,77 @@
1
+ module Jekyll
2
+ module J1Paginator::AutoPages
3
+
4
+ #
5
+ # This function is called right after the main generator is triggered by Jekyll
6
+ # This code is adapted from Stephen Crosby's code https://github.com/stevecrozz
7
+ def self.create_autopages(site)
8
+
9
+ # Get the configuration for the auto pages
10
+ autopage_config = Jekyll::Utils.deep_merge_hashes(DEFAULT, site.config['autopages'] || {})
11
+ pagination_config = Jekyll::Utils.deep_merge_hashes(Jekyll::J1Paginator::Generator::DEFAULT, site.config['pagination'] || {})
12
+
13
+ # If disabled then don't do anything
14
+ if !autopage_config['enabled'] || autopage_config['enabled'].nil?
15
+ Jekyll.logger.info "AutoPages:","Disabled/Not configured in site.config."
16
+ return
17
+ end
18
+
19
+ # TODO: Should I detect here and disable if we're running the legacy paginate code???!
20
+
21
+ # Simply gather all documents across all pages/posts/collections that we have
22
+ # we could be generating quite a few empty pages but the logic is just vastly simpler than trying to
23
+ # figure out what tag/category belong to which collection.
24
+ posts_to_use = Utils.collect_all_docs(site.collections)
25
+
26
+ ###############################################
27
+ # Generate the Tag pages if enabled
28
+ createtagpage_lambda = lambda do | autopage_tag_config, pagination_config, layout_name, tag, tag_original_name |
29
+ site.pages << TagAutoPage.new(site, site.dest, autopage_tag_config, pagination_config, layout_name, tag, tag_original_name)
30
+ end
31
+ autopage_create(autopage_config, pagination_config, posts_to_use, 'tags', 'tags', createtagpage_lambda) # Call the actual function
32
+
33
+
34
+ ###############################################
35
+ # Generate the category pages if enabled
36
+ createcatpage_lambda = lambda do | autopage_cat_config, pagination_config, layout_name, category, category_original_name |
37
+ site.pages << CategoryAutoPage.new(site, site.dest, autopage_cat_config, pagination_config, layout_name, category, category_original_name)
38
+ end
39
+ autopage_create(autopage_config, pagination_config,posts_to_use, 'categories', 'categories', createcatpage_lambda) # Call the actual function
40
+
41
+ ###############################################
42
+ # Generate the Collection pages if enabled
43
+ createcolpage_lambda = lambda do | autopage_col_config, pagination_config, layout_name, coll_name, coll_original_name |
44
+ site.pages << CollectionAutoPage.new(site, site.dest, autopage_col_config, pagination_config, layout_name, coll_name, coll_original_name)
45
+ end
46
+ autopage_create(autopage_config, pagination_config,posts_to_use, 'collections', '__coll', createcolpage_lambda) # Call the actual function
47
+
48
+ end # create_autopages
49
+
50
+
51
+ # STATIC: this function actually performs the steps to generate the autopages. It uses a lambda function to delegate the creation of the individual
52
+ # page types to the calling code (this way all features can reuse the logic).
53
+ #
54
+ def self.autopage_create(autopage_config, pagination_config, posts_to_use, configkey_name, indexkey_name, createpage_lambda )
55
+ if !autopage_config[configkey_name].nil?
56
+ ap_sub_config = autopage_config[configkey_name]
57
+ if ap_sub_config ['enabled']
58
+ Jekyll.logger.info "AutoPages:","Generating #{configkey_name} pages"
59
+
60
+ # Roll through all documents in the posts collection and extract the tags
61
+ index_keys = Utils.ap_index_posts_by(posts_to_use, indexkey_name) # Cannot use just the posts here, must use all things.. posts, collections...
62
+
63
+ index_keys.each do |index_key, value|
64
+ # Iterate over each layout specified in the config
65
+ ap_sub_config ['layouts'].each do | layout_name |
66
+ # Use site.dest here as these pages are never created in the actual source but only inside the _site folder
67
+ 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
68
+ end
69
+ end
70
+ else
71
+ Jekyll.logger.info "AutoPages:","#{configkey_name} pages are disabled/not configured in site.config."
72
+ end
73
+ end
74
+ end
75
+
76
+ end # module J1Paginator
77
+ end # module Jekyll
@@ -0,0 +1,40 @@
1
+ module Jekyll
2
+ module J1Paginator::AutoPages
3
+
4
+ # The default configuration for the AutoPages
5
+ DEFAULT = {
6
+ 'enabled' => false,
7
+ 'tags' => {
8
+ 'layouts' => ['autopage_tags.html'],
9
+ 'title' => 'Posts tagged with :tag',
10
+ 'permalink' => '/tag/:tag',
11
+ 'enabled' => true,
12
+ 'slugify' => {
13
+ 'mode' => 'none', # [raw default pretty ascii latin], none gives back the same string
14
+ 'cased'=> false # If cased is true, all uppercase letters in the result string are replaced with their lowercase counterparts.
15
+ }
16
+ },
17
+ 'categories' => {
18
+ 'layouts' => ['autopage_category.html'],
19
+ 'title' => 'Posts in category :cat',
20
+ 'permalink' => '/category/:cat',
21
+ 'enabled' => true,
22
+ 'slugify' => {
23
+ 'mode' => 'none', # [raw default pretty ascii latin], none gives back the same string
24
+ 'cased'=> false # If cased is true, all uppercase letters in the result string are replaced with their lowercase counterparts.
25
+ }
26
+ },
27
+ 'collections' => {
28
+ 'layouts' => ['autopage_collection.html'],
29
+ 'title' => 'Posts in collection :coll',
30
+ 'permalink' => '/collection/:coll',
31
+ 'enabled' => true,
32
+ 'slugify' => {
33
+ 'mode' => 'none', # [raw default pretty ascii latin], none gives back the same string
34
+ 'cased'=> false # If cased is true, all uppercase letters in the result string are replaced with their lowercase counterparts.
35
+ }
36
+ }
37
+ }
38
+
39
+ end # module J1Paginator::AutoPages
40
+ end # module Jekyll
@@ -0,0 +1,60 @@
1
+ module Jekyll
2
+ module J1Paginator::AutoPages
3
+
4
+ class BaseAutoPage < Jekyll::Page
5
+ def initialize(site, base, autopage_config, pagination_config, layout_name, set_autopage_data_lambda, get_autopage_permalink_lambda, get_autopage_title_lambda, display_name)
6
+ @site = site
7
+ @base = base
8
+ @name = 'index.html'
9
+
10
+ layout_dir = '_layouts'
11
+
12
+ # Path is only used by the convertible module and accessed below when calling read_yaml
13
+ # Handling themes stored in a gem
14
+ @path = if site.in_theme_dir(site.source) == site.source # we're in a theme
15
+ site.in_theme_dir(site.source, layout_dir, layout_name)
16
+ else
17
+ site.in_source_dir(site.source, layout_dir, layout_name)
18
+ end
19
+
20
+ self.process(@name) # Creates the base name and extension
21
+ self.read_yaml(File.join(site.source, layout_dir), layout_name)
22
+
23
+ # Merge the config with any config that might already be defined in the layout
24
+ pagination_layout_config = Jekyll::Utils.deep_merge_hashes( pagination_config, self.data['pagination'] || {} )
25
+
26
+ # Read any possible autopage overrides in the layout page
27
+ autopage_layout_config = Jekyll::Utils.deep_merge_hashes( autopage_config, self.data['autopages'] || {} )
28
+
29
+ # Now set the page specific pagination data
30
+ set_autopage_data_lambda.call(pagination_layout_config)
31
+
32
+ # Get permalink structure
33
+ permalink_formatted = get_autopage_permalink_lambda.call(autopage_layout_config['permalink'])
34
+
35
+ # Construct the title
36
+ page_title = autopage_layout_config['title']
37
+
38
+ # NOTE: Should we set this before calling read_yaml as that function validates the permalink structure
39
+ self.data['permalink'] = permalink_formatted
40
+ @url = File.join(permalink_formatted, @name)
41
+ @dir = permalink_formatted
42
+
43
+ self.data['layout'] = File.basename(layout_name, File.extname(layout_name))
44
+ self.data['title'] = get_autopage_title_lambda.call( page_title )
45
+ self.data['pagination'] = pagination_layout_config # Store the pagination configuration
46
+
47
+ # Add the auto page flag in there to be able to detect the page (necessary when figuring out where to load it from)
48
+ # TODO: Need to re-think this variable!!!
49
+ self.data['autopage'] = {"layout_path" => File.join( layout_dir, layout_name ), 'display_name' => display_name.to_s }
50
+
51
+ data.default_proc = proc do |_, key|
52
+ site.frontmatter_defaults.find(File.join(layout_dir, layout_name), type, key)
53
+ end
54
+
55
+ # Trigger a page event
56
+ #Jekyll::Hooks.trigger :pages, :post_init, self
57
+ end #function initialize
58
+ end #class BaseAutoPage
59
+ end # module J1Paginator
60
+ end # module Jekyll
@@ -0,0 +1,32 @@
1
+ module Jekyll
2
+ module J1Paginator::AutoPages
3
+
4
+ class CategoryAutoPage < BaseAutoPage
5
+ def initialize(site, base, autopage_config, pagination_config, layout_name, category, category_name)
6
+
7
+ # Do we have a slugify configuration available
8
+ slugify_config = autopage_config.is_a?(Hash) && autopage_config.has_key?('slugify') ? autopage_config['slugify'] : nil
9
+
10
+ # Construc the lambda function to set the config values
11
+ # this function received the pagination config hash and manipulates it
12
+ set_autopage_data_lambda = lambda do | in_config |
13
+ in_config['category'] = category
14
+ in_config['collection'] = site.collections.keys
15
+ end
16
+
17
+ get_autopage_permalink_lambda = lambda do |permalink_pattern|
18
+ return Utils.format_cat_macro(permalink_pattern, category, slugify_config)
19
+ end
20
+
21
+ get_autopage_title_lambda = lambda do |title_pattern|
22
+ return Utils.format_cat_macro(title_pattern, category, slugify_config)
23
+ end
24
+
25
+ # Call the super constuctor with our custom lambda
26
+ super(site, base, autopage_config, pagination_config, layout_name, set_autopage_data_lambda, get_autopage_permalink_lambda, get_autopage_title_lambda, category_name)
27
+
28
+ end #function initialize
29
+
30
+ end #class CategoryAutoPage
31
+ end # module J1Paginator
32
+ end # module Jekyll
@@ -0,0 +1,31 @@
1
+ module Jekyll
2
+ module J1Paginator::AutoPages
3
+
4
+ class CollectionAutoPage < BaseAutoPage
5
+ def initialize(site, base, autopage_config, pagination_config, layout_name, collection, collection_name)
6
+
7
+ # Do we have a slugify configuration available
8
+ slugify_config = autopage_config.is_a?(Hash) && autopage_config.has_key?('slugify') ? autopage_config['slugify'] : nil
9
+
10
+ # Construc the lambda function to set the config values
11
+ # this function received the pagination config hash and manipulates it
12
+ set_autopage_data_lambda = lambda do | in_config |
13
+ in_config['collection'] = collection
14
+ end
15
+
16
+ get_autopage_permalink_lambda = lambda do |permalink_pattern|
17
+ return Utils.format_coll_macro(permalink_pattern, collection, slugify_config)
18
+ end
19
+
20
+ get_autopage_title_lambda = lambda do |title_pattern|
21
+ return Utils.format_coll_macro(title_pattern, collection, slugify_config)
22
+ end
23
+
24
+ # Call the super constuctor with our custom lambda
25
+ super(site, base, autopage_config, pagination_config, layout_name, set_autopage_data_lambda, get_autopage_permalink_lambda, get_autopage_title_lambda, collection_name)
26
+
27
+ end #function initialize
28
+
29
+ end #class CollectionAutoPage
30
+ end # module J1Paginator
31
+ end # module Jekyll
@@ -0,0 +1,32 @@
1
+ module Jekyll
2
+ module J1Paginator::AutoPages
3
+
4
+ class TagAutoPage < BaseAutoPage
5
+ def initialize(site, base, autopage_config, pagination_config, layout_name, tag, tag_name)
6
+
7
+ # Do we have a slugify configuration available
8
+ slugify_config = autopage_config.is_a?(Hash) && autopage_config.has_key?('slugify') ? autopage_config['slugify'] : nil
9
+
10
+ # Construc the lambda function to set the config values,
11
+ # this function received the pagination config hash and manipulates it
12
+ set_autopage_data_lambda = lambda do | config |
13
+ config['tag'] = tag
14
+ config['collection'] = site.collections.keys
15
+ end
16
+
17
+ get_autopage_permalink_lambda = lambda do |permalink_pattern|
18
+ return Utils.format_tag_macro(permalink_pattern, tag, slugify_config)
19
+ end
20
+
21
+ get_autopage_title_lambda = lambda do |title_pattern|
22
+ return Utils.format_tag_macro(title_pattern, tag, slugify_config)
23
+ end
24
+
25
+ # Call the super constuctor with our custom lambda
26
+ super(site, base, autopage_config, pagination_config, layout_name, set_autopage_data_lambda, get_autopage_permalink_lambda, get_autopage_title_lambda, tag_name)
27
+
28
+ end #function initialize
29
+
30
+ end #class TagAutoPage
31
+ end # module J1Paginator
32
+ end # module Jekyll