jekyll-paginate-v2 1.2.0 → 1.3.1

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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 80659d18067d2e6e70c308778083386e55baa867
4
- data.tar.gz: 24d4018f4b1df421583e0412079e6fd71cb6ab9d
3
+ metadata.gz: e40078ff1d6e37ea3e12e5c00a6d19918532cc9f
4
+ data.tar.gz: 5b48bf3d7056f77ffe6a5644127bd8f48460d75c
5
5
  SHA512:
6
- metadata.gz: 8a49c16c2a1e5e450e39a169362a4702ec769160338a9ad081ad0e3a84a4c118117e3ea6039debdd16f05d2d3de35b7837558bf967ac06b5a62f5ecbf065a849
7
- data.tar.gz: f34d20de449ce50b39f7c6015425f0f9f8b4ee52d7e04b9faaf5961470b90e6c2e4c0e6fc486714b7c11d29e20394c09c6d25e9c6e690cac14a5186938801594
6
+ metadata.gz: 4b30be9bf65547b50bb37bbb088e3f6836efcae6f0e5ea44c44109502b38b1f078f89f5676afdef1555a852cfe6c8efc8f6f04f31a90eeaed164272445a8c31f
7
+ data.tar.gz: 84286d55555990445f81c14245e7371277ad12d6d1867f32129f709f4f51dd9a4792619e5268b3761de80f757bee72c905b13e157d81a2da2d1f76eb65b0cfd9
data/README.md CHANGED
@@ -18,7 +18,7 @@ gem install jekyll-paginate-v2
18
18
 
19
19
  Update your [_config.yml](#site-configuration) and [pages](#page-configuration).
20
20
 
21
- > Although backwards compatible, this gem needs slightly extended [site yml](#site-configuration) configuration and adds miniscule new front-matter for the [paging templates](#page-configuration) configuration elements.
21
+ > Although fully backwards compatible, to enable the new features this gem needs slightly extended [site yml](#site-configuration) configuration and miniscule additional new front-matter for the [paging templates](#page-configuration) configuration elements.
22
22
 
23
23
  Now you're ready to run `jekyll serve` and your paginated files should be generated.
24
24
 
@@ -36,15 +36,12 @@ In addition to all the features offered by the older [jekyll-paginate gem](https
36
36
  7. Fully customizable permalink format. E.g `/page:num/` or `/page/:num/` or `/:num/` or really anything you want.
37
37
  8. Optional title suffix for paginated pages (e.g. _Index - Page 2_)
38
38
 
39
- All this while being fully backwards compatible with the old [jekyll-paginate](https://github.com/jekyll/jekyll-paginate) gem (requires minimal additional front-matter, see [page-configuration](#page-configuration)).
39
+ All this while being fully backwards compatible with the old [jekyll-paginate](https://github.com/jekyll/jekyll-paginate) gem.
40
40
 
41
41
  ## Issues / to-be-completed
42
- * Not fully compatible with the old jekyll-paginate plugin configuration yet.
43
42
  * Incomplete unit-tests
44
43
  * Missing integration tests [#2](https://github.com/jekyll/jekyll-paginate/pull/2)
45
44
  * Missing more detailed examples
46
- * Code is still too tightly coupled with `site` [#26](https://github.com/jekyll/jekyll-paginate/issues/26)
47
- * Unable to paginate _pages_ (still under consideration)
48
45
  * Unable to auto-generate category/tag/language pagination pages. Still requires programmer to specify the pages him/herself.
49
46
  * _Exclude_ filter not implemented [#6](https://github.com/jekyll/jekyll-paginate/issues/6)
50
47
 
@@ -107,6 +104,20 @@ pagination:
107
104
  ############################################################
108
105
  ```
109
106
 
107
+ ### Backwards compatibility with jekyll-paginate
108
+ This gem is fully backwards compatible with the old [jekyll-paginate](https://github.com/jekyll/jekyll-paginate) gem and can be used as a zero-configuration replacement for it. If the old site config is detected then the gem will fall back to the old logic of pagination.
109
+
110
+ > You cannot run both the new pagination logic and the old one at the same time
111
+
112
+ The following `_config.yml` settings are honored when running this gem in compatability mode
113
+
114
+ ``` yml
115
+ paginate: 8
116
+ paginate_path: "/legacy/page:num/"
117
+ ```
118
+
119
+ See more about the old style of pagination at the [jekyll-paginate](https://github.com/jekyll/jekyll-paginate) page.
120
+
110
121
  ## Page configuration
111
122
 
112
123
  To enable pagination on a page (i.e. make that page a template for pagination) then simply include the minimal pagination configuration in the page front-matter:
@@ -161,9 +172,12 @@ Enabling pagination for specific categories, tags or locales is as simple as add
161
172
  Filter single category 'software'
162
173
 
163
174
  ``` yml
175
+ ---
176
+ layout: post
164
177
  pagination:
165
178
  enabled: true
166
179
  category: software
180
+ ---
167
181
  ```
168
182
 
169
183
  Filter multiple categories (lists only posts belonging to all categories)
@@ -7,14 +7,14 @@ Gem::Specification.new do |spec|
7
7
  spec.name = "jekyll-paginate-v2"
8
8
  spec.version = Jekyll::PaginateV2::VERSION
9
9
  spec.platform = Gem::Platform::RUBY
10
- spec.date = '2016-11-19'
10
+ spec.date = DateTime.now.strftime('%Y-%m-%d')
11
11
  spec.authors = ["Sverrir Sigmundarson"]
12
12
  spec.email = ["jekyll@sverrirs.com"]
13
13
  spec.homepage = "https://github.com/sverrirs/jekyll-paginate-v2"
14
14
  spec.license = "MIT"
15
15
 
16
16
  spec.summary = %q{Pagination Generator for Jekyll 3}
17
- spec.description = %q{An enhanced in-place replacement for the previously built-in jekyll-paginate gem offering full backwards compatability as well as a slew of new frequently requested features}
17
+ 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.}
18
18
 
19
19
  spec.files = `git ls-files -z`.split("\x0")
20
20
  #spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
@@ -11,6 +11,7 @@
11
11
 
12
12
  require "jekyll-paginate-v2/version"
13
13
  require "jekyll-paginate-v2/defaults"
14
+ require "jekyll-paginate-v2/compatibilityUtils"
14
15
  require "jekyll-paginate-v2/utils"
15
16
  require "jekyll-paginate-v2/paginator"
16
17
  require "jekyll-paginate-v2/paginationModel"
@@ -0,0 +1,67 @@
1
+ module Jekyll
2
+ module PaginateV2
3
+
4
+ #
5
+ # Static utility functions that provide backwards compatibility with the old
6
+ # jekyll-paginate gem that this new version superseeds (this code is here to ensure)
7
+ # that sites still running the old gem work without problems
8
+ # (REMOVE AFTER 2018-01-01)
9
+ #
10
+ class CompatibilityUtils
11
+
12
+ # Public: Find the Jekyll::Page which will act as the pager template
13
+ #
14
+ # Returns the Jekyll::Page which will act as the pager template
15
+ def self.template_page(site_pages, config_source, config_paginate_path)
16
+ site_pages.select do |page|
17
+ CompatibilityUtils.pagination_candidate?(config_source, config_paginate_path, page)
18
+ end.sort do |one, two|
19
+ two.path.size <=> one.path.size
20
+ end.first
21
+ end
22
+
23
+ # Static: Determine if a page is a possible candidate to be a template page.
24
+ # Page's name must be `index.html` and exist in any of the directories
25
+ # between the site source and `paginate_path`.
26
+ def self.pagination_candidate?(config_source, config_paginate_path, page)
27
+ page_dir = File.dirname(File.expand_path(Utils.remove_leading_slash(page.path), config_source))
28
+ paginate_path = Utils.remove_leading_slash(config_paginate_path)
29
+ paginate_path = File.expand_path(paginate_path, config_source)
30
+ page.name == 'index.html' && CompatibilityUtils.in_hierarchy(config_source, page_dir, File.dirname(paginate_path))
31
+ end
32
+
33
+ # Determine if the subdirectories of the two paths are the same relative to source
34
+ #
35
+ # source - the site source
36
+ # page_dir - the directory of the Jekyll::Page
37
+ # paginate_path - the absolute paginate path (from root of FS)
38
+ #
39
+ # Returns whether the subdirectories are the same relative to source
40
+ def self.in_hierarchy(source, page_dir, paginate_path)
41
+ return false if paginate_path == File.dirname(paginate_path)
42
+ return false if paginate_path == Pathname.new(source).parent
43
+ page_dir == paginate_path ||
44
+ CompatibilityUtils.in_hierarchy(source, page_dir, File.dirname(paginate_path))
45
+ end
46
+
47
+ # Paginates the blog's posts. Renders the index.html file into paginated
48
+ # directories, e.g.: page2/index.html, page3/index.html, etc and adds more
49
+ # site-wide data.
50
+ #
51
+ def self.paginate(legacy_config, all_posts, page, &page_create_proc )
52
+ pages = Utils.calculate_number_of_pages(all_posts, legacy_config['per_page'].to_i)
53
+ (1..pages).each do |num_page|
54
+ pager = Paginator.new( legacy_config['per_page'], legacy_config['permalink'], all_posts, num_page, pages, page.url )
55
+ if num_page > 1
56
+ newpage = page_create_proc.call( page.dir, page.name )
57
+ newpage.pager = pager
58
+ newpage.dir = Utils.paginate_path(page.url, num_page, legacy_config['permalink'])
59
+ else
60
+ page.pager = pager
61
+ end
62
+ end
63
+ end
64
+
65
+ end # class CompatibilityUtils
66
+ end # module PaginateV2
67
+ end # module Jekyll
@@ -11,7 +11,8 @@ module Jekyll
11
11
  'page_num' => 1,
12
12
  'sort_reverse' => false,
13
13
  'sort_field' => 'date',
14
- 'limit' => 0 # Limit how many content objects to paginate (default: 0, means all)
14
+ 'limit' => 0, # Limit how many content objects to paginate (default: 0, means all)
15
+ 'legacy' => false # Internal value, do not use (will be removed after 2018-01-01)
15
16
  }
16
17
 
17
18
  end # module PaginateV2
@@ -22,10 +22,30 @@ module Jekyll
22
22
 
23
23
  # Retrieve and merge the pagination configuration from the site yml file
24
24
  default_config = DEFAULT.merge(site.config['pagination'] || {})
25
-
25
+
26
+ # Compatibility Note: (REMOVE AFTER 2018-01-01)
27
+ # If the legacy paginate logic is configured then read those values and merge with config
28
+ if !site.config['paginate'].nil?
29
+ # You cannot run both the new code and the old code side by side
30
+ if !site.config['pagination'].nil?
31
+ err_msg = "The new jekyll-paginate-v2 and the old jekyll-paginate logic cannot both be configured in the site config at the same time. Please disable the old 'paginate:num' config settings."
32
+ Jekyll.logger.error err_msg
33
+ raise ArgumentError.new(err_msg)
34
+ end
35
+
36
+ default_config['per_page'] = site.config['paginate'].to_i
37
+ default_config['legacy_source'] = site.config['source']
38
+ if !site.config['paginate_path'].nil?
39
+ default_config['permalink'] = site.config['paginate_path'].to_s
40
+ end
41
+ # In case of legacy, enable pagination by default
42
+ default_config['enabled'] = true
43
+ default_config['legacy'] = true
44
+ end # Compatibility END (REMOVE AFTER 2018-01-01)
45
+
26
46
  # If disabled then simply quit
27
47
  if !default_config['enabled']
28
- Jekyll.logger.info "Pagination:","disabled in site.config."
48
+ Jekyll.logger.info "Pagination:","Disabled in site.config."
29
49
  return
30
50
  end
31
51
 
@@ -57,7 +77,11 @@ module Jekyll
57
77
  ################ 3 ####################
58
78
  # Now create and call the model with the real-life page creation proc and site data
59
79
  model = PaginationModel.new()
60
- model.run(default_config, all_pages, site_title, all_posts, &page_create_lambda)
80
+ if( default_config['legacy'] ) #(REMOVE AFTER 2018-01-01)
81
+ model.run_compatability(default_config, all_pages, site_title, all_posts, &page_create_lambda) #(REMOVE AFTER 2018-01-01)
82
+ else
83
+ model.run(default_config, all_pages, site_title, all_posts, &page_create_lambda)
84
+ end
61
85
 
62
86
  end
63
87
  end # class PaginationGenerator
@@ -4,10 +4,6 @@ module Jekyll
4
4
  class PaginationModel
5
5
 
6
6
  def run(default_config, site_pages, site_title, all_posts, &page_create_proc)
7
- #if !block_given?
8
- # raise ArgumentError.new("No page creation block given, cannot continue.")
9
- #end
10
-
11
7
  # By default if pagination is enabled we attempt to find all index.html pages in the site
12
8
  templates = self.discover_paginate_templates(site_pages)
13
9
  if( templates.size.to_i <= 0 )
@@ -25,7 +21,6 @@ module Jekyll
25
21
 
26
22
  # Now for each template page generate the paginator for it
27
23
  for template in templates
28
-
29
24
  # All pages that should be paginated need to include the pagination config element
30
25
  if template.data['pagination'].is_a?(Hash)
31
26
  template_config = default_config.merge(template.data['pagination'])
@@ -41,8 +36,30 @@ module Jekyll
41
36
  end
42
37
  end
43
38
  end #for
39
+ end # function run
40
+
41
+ #
42
+ # This function is here to retain the old compatability logic with the jekyll-paginate gem
43
+ # no changes should be made to this function and it should be retired and deleted after 2018-01-01
44
+ # (REMOVE AFTER 2018-01-01)
45
+ #
46
+ def run_compatability(legacy_config, site_pages, site_title, all_posts, &page_create_proc)
47
+
48
+ if( date = Date.strptime("20180101","%Y%m%d") <= Date.today )
49
+ raise ArgumentError.new("Legacy jekyll-paginate configuration compatibility mode has expired. Please upgrade to jekyll-paginate-v2 configuration.")
50
+ end
51
+
52
+ Jekyll.logger.warn "Pagination:", "Detected legacy jekyll-paginate logic being run. "+
53
+ "Please update your configs to use the new pagination logic (gem jekyll-paginate-v2). This compatibility function "+
54
+ "will stop working after Jan 1st 2018 and your site build will throw an error."
44
55
 
45
- end # function generate
56
+ if template = CompatibilityUtils.template_page(site_pages, legacy_config['legacy_source'], legacy_config['permalink'])
57
+ CompatibilityUtils.paginate(legacy_config, all_posts, template, &page_create_proc)
58
+ else
59
+ Jekyll.logger.warn "Pagination:", "Legacy pagination is enabled, but I couldn't find " +
60
+ "an index.html page to use as the pagination template. Skipping pagination."
61
+ end
62
+ end # function run_compatability (REMOVE AFTER 2018-01-01)
46
63
 
47
64
  #
48
65
  # Rolls through all the pages passed in and finds all pages that have pagination enabled on them.
@@ -185,7 +202,7 @@ module Jekyll
185
202
  end
186
203
 
187
204
  # Calculate the max number of pagination-pages based on the configured per page value
188
- total_pages = self.calculate_number_of_pages(using_posts, config['per_page'])
205
+ total_pages = Utils.calculate_number_of_pages(using_posts, config['per_page'])
189
206
 
190
207
  # If a upper limit is set on the number of total pagination pages then impose that now
191
208
  if config['limit'] && config['limit'].to_i > 0 && config['limit'].to_i < total_pages
@@ -216,17 +233,7 @@ module Jekyll
216
233
  end
217
234
  end
218
235
  end # function paginate
219
-
220
- # Calculate the number of pages.
221
- #
222
- # all_posts - The Array of all Posts.
223
- # per_page - The Integer of entries per page.
224
- #
225
- # Returns the Integer number of pages.
226
- def calculate_number_of_pages(all_posts, per_page)
227
- (all_posts.size.to_f / per_page.to_i).ceil
228
- end
229
-
236
+
230
237
  end # class PaginationV2
231
238
 
232
239
  end # module PaginateV2
@@ -7,6 +7,16 @@ module Jekyll
7
7
  #
8
8
  class Utils
9
9
 
10
+ # Static: Calculate the number of pages.
11
+ #
12
+ # all_posts - The Array of all Posts.
13
+ # per_page - The Integer of entries per page.
14
+ #
15
+ # Returns the Integer number of pages.
16
+ def self.calculate_number_of_pages(all_posts, per_page)
17
+ (all_posts.size.to_f / per_page.to_i).ceil
18
+ end
19
+
10
20
  # Static: Return the pagination path of the page
11
21
  #
12
22
  # site - the Jekyll::Site object
@@ -1,5 +1,5 @@
1
1
  module Jekyll
2
2
  module PaginateV2
3
- VERSION = "1.2.0"
3
+ VERSION = "1.3.1"
4
4
  end
5
5
  end
@@ -5,6 +5,7 @@ require 'jekyll'
5
5
  require_relative '../lib/jekyll-paginate-v2/version'
6
6
  require_relative '../lib/jekyll-paginate-v2/defaults'
7
7
  require_relative '../lib/jekyll-paginate-v2/utils'
8
+ require_relative '../lib/jekyll-paginate-v2/compatibilityUtils'
8
9
  require_relative '../lib/jekyll-paginate-v2/paginator'
9
10
  require_relative '../lib/jekyll-paginate-v2/paginationModel'
10
11
  require_relative '../lib/jekyll-paginate-v2/paginationGenerator'
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: jekyll-paginate-v2
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.2.0
4
+ version: 1.3.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Sverrir Sigmundarson
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2016-11-19 00:00:00.000000000 Z
11
+ date: 2016-11-26 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: jekyll
@@ -52,9 +52,10 @@ dependencies:
52
52
  - - ">="
53
53
  - !ruby/object:Gem::Version
54
54
  version: '0'
55
- description: An enhanced in-place replacement for the previously built-in jekyll-paginate
56
- gem offering full backwards compatability as well as a slew of new frequently requested
57
- features
55
+ description: An enhanced zero-configuration in-place replacement for the now decomissioned
56
+ built-in jekyll-paginate gem. This pagination gem offers full backwards compatability
57
+ as well as a slew of new frequently requested features with minimal additional site
58
+ and page configuration.
58
59
  email:
59
60
  - jekyll@sverrirs.com
60
61
  executables: []
@@ -68,6 +69,7 @@ files:
68
69
  - Rakefile
69
70
  - jekyll-paginate-v2.gemspec
70
71
  - lib/jekyll-paginate-v2.rb
72
+ - lib/jekyll-paginate-v2/compatibilityUtils.rb
71
73
  - lib/jekyll-paginate-v2/defaults.rb
72
74
  - lib/jekyll-paginate-v2/paginationGenerator.rb
73
75
  - lib/jekyll-paginate-v2/paginationModel.rb