coffeebrew_jekyll_paginate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ea621dece76bb070ca7414e7ae18bba2b01729d3e4be3a58f16dfd040e091bf
+  data.tar.gz: ba842e477f22c13151198164443cafdca41be95ad8ced809d41655f124bcb9ee
+SHA512:
+  metadata.gz: d4c427ece85c3bc8c60737ebc47d7c130a7de6907bda74abb164184fe735b3d16f5244e448191b17488798ff4573191b9a2c256739201ca50a21ebcdacc36e0f
+  data.tar.gz: 007e60e476b29d01456e5cf6675f1cd48c4c49d4ebb68f59317c4867e4fbf6e5524f10549107352940ebfdedbf880eef0844ec6e6df2d468ac76fadb08bfef9e

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Version 0.1.0
+
+[View version doc](https://github.com/coffeebrewapps/coffeebrew_jekyll_paginate/blob/v0.1.0/README.md)
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Coffee Brew Apps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,704 @@
+# Jekyll Paginate Plugin
+
+A Jekyll plugin to generate site pagination for collections.
+
+[![Continuous Integration](https://github.com/coffeebrewapps/coffeebrew_jekyll_paginate/actions/workflows/ruby.yml/badge.svg)](https://github.com/coffeebrewapps/coffeebrew_jekyll_paginate/actions/workflows/ruby.yml) [![Gem Version](https://badge.fury.io/rb/coffeebrew_jekyll_paginate.svg)](https://badge.fury.io/rb/coffeebrew_jekyll_paginate)
+
+## Installation
+
+Add this line to your site's Gemfile:
+
+```ruby
+gem 'coffeebrew_jekyll_paginate'
+```
+
+And then add this line to your site's `_config.yml`:
+
+```yml
+plugins:
+  - coffeebrew_jekyll_paginate
+```
+
+By default, the plugin doesn't generate any pagination. You need to specify which collections to be paginated. For
+example,
+
+```yml
+---
+coffeebrew_jekyll_paginate:
+  collections:
+    books:
+```
+
+Assuming layouts have been setup (see more in [Layouts](#layouts)), then, the plugin will generate paginated
+collections using the default config below:
+
+```yml
+individual_page_pagination: false
+frontmatter_defaults_key: "paginated_%{collection_type}"
+first_page_as_root:
+  enabled: false
+permalink: /:collection_type/:page_num_one_index
+index_page: "index"
+per_page: 5
+sort_field: "date"
+sort_reverse: true
+page_num_label: "%{page_num_one_index}"
+```
+
+An example of the generated directory structure is as such:
+
+```bash
+_site/
+├── books
+│   ├── 1
+│   │   ├── index.html
+│   └── 2
+│       └── index.html
+└── index.html
+```
+
+## Configuration
+
+You can configure for as many collections as needed, and configure a site-wide pagination config, or configure for each
+collection to use its own configuration. If there is no configuration for the site default, or the collection, the
+plugin will use the default values as previously mentioned.
+
+### Site-wide defaults
+
+For example, you can configure site-wide defaults that override the plugin's defaults, which will be used for all the
+collections enabled.
+
+```yml
+coffeebrew_jekyll_paginate:
+  defaults:
+    individual_page_pagination: true
+    first_page_as_root:
+      enabled: true
+      permalink: /
+      index_page: /:collection_type
+    per_page: 3
+    page_num_label: "Page %{page_num_one_index}"
+  collections:
+    books:
+    posts:
+```
+
+If you do override the configuration, the plugin will perform a simple validation on your overrides according to these rules:
+
+### Frontmatter defaults key config
+
+This tells the plugin what is the key used for setting defaults. For example, the plugin will use `paginated_posts` for
+`posts` type by default, and this will allow Jekyll to lookup defaults for `type: "paginated_posts"` in `_config.yml`.
+
+```yml
+defaults:
+  - scope:
+      path: ""
+      type: "paginated_posts"
+    values:
+      layout: "posts_index"
+```
+
+### Individual page pagination config
+
+If set to `true`, this tells the plugin to generate previous/next pagination for individual collection pages. This is
+useful if you want to have individual page-level pagination to navigate to the previous or next page. For example:
+
+```yml
+---
+layout: default
+---
+<h1>Posts</h1>
+{% raw %}
+{{ content }}
+
+<div class="pagination">
+  <ul class="pager">
+    <li class="previous">
+      <a href="{{ page.paginator.previous_page_path }}">< {{ page.paginator.previous_page.title }}</a>
+    </li>
+    <li class="next">
+      <a href="{{ page.paginator.next_page_path }}">{{ page.paginator.next_page.title }} ></a>
+    </li>
+  </ul>
+</div>
+{% endraw %}
+```
+
+### First page as root config
+
+This tells the plugin to generate the first page outside of the collection directory in the paginated set. For example,
+if there are 4 pages in the paginated books collection, then the first page will be rendered in `/books.html`, and the
+other pages will be rendered as `/books/2/index.html`, `/books/3/index.html` and `/books/4/index.html`.
+
+This will be useful if you want to have the first page as part of your root pages and include it in the navigation.
+
+| Key | Allowed Value(s) | Default | Remark |
+| --- | --- | --- | --- |
+| enabled | Boolean | false | If set to `true`, then the plugin will render the first page in a separate path as defined by the `permalink` and `index_page` below. |
+| permalink | String | nil | The directory in which to generate the first page. Normally this will be `/` if you want it to be a root-level page. |
+| index_page | String | nil | The filename of the first page. Normally this will be the name corresponding to the collection. |
+
+If `enabled` is `false`, both `permalink` and `index_page` will be ignored, and the plugin will generate the first page
+the same way as the remaining pages.
+
+### Pagination config
+
+This tells the plugin how to generate the pagination pages.
+
+| Key | Allowed Value(s) | Default | Remark |
+| --- | --- | --- | --- |
+| permalink | String | /:collection_type/:page_num_one_index | The directory in which to generate the page. |
+| index_page | String | index | The filename of the page. |
+| per_page | Integer | 5 | The number of collection items in each page. |
+| sort_field | String | date | The field to be used to sort the collection for deterministic pagination. |
+| sort_reverse | Boolean | true | The collection will be sorted in reverse if set to `true`. |
+| page_num_label | String | %{page_num_one_index} | The format string for the page number label. |
+
+A few placeholders are available to be used in the `permalink`, `index_page` and `page_num_label`:
+
+| Field | Description |
+| --- | --- |
+| collection_type | This is the collection type current page, eg. `posts`. |
+| page_num_zero_index | This will be the 0-index page number of the current page. |
+| page_num_one_index | This will be the 1-index page number of the current page. |
+
+### Validation
+
+If the config overrides have invalid structure, keys or values, the plugin will raise a
+`Jekyll::Errors::InvalidConfigurationError` during build.
+
+## Layouts
+
+The plugin does not provide a default layout. You will need to create your own layout in `_layouts` and configure the
+defaults in `_config.yml`, for example, if you want to paginate the `books` collection, then you need to configure
+the layout for the collection:
+
+```yml
+---
+defaults:
+  - scope:
+      type: "paginated_books"
+    values:
+      layout: "books_pagination"
+  - scope:
+      type: "books"
+    values:
+      layout: "book"
+      permalink: /books/:name:output_ext
+```
+
+As mentioned earlier, you need to set the `scope.type` here to match the `frontmatters_defaults_key` config of the
+plugin. Note that there are 2 layouts configured here, `books_pagination` is used for the paginated collection page,
+and `book` is used for the individual book page.
+
+In addition to Jekyll's default page data, you can also use the additional page data and page's paginator data generated
+by the plugin in the layout:
+
+### Paginated collection page
+
+Use `page` to access the fields below.
+
+| Field | Description |
+| --- | --- |
+| title | Current page's title. |
+| collection | Current page's collection. |
+| collection_type | Current page's collection type. |
+| page_num_zero_index | Current page's 0-index page number. |
+| page_num_one_index | Current page's 1-index page number. |
+| page_num_label | Current page's page number label. |
+| full_url | Current page full url. Can be used to match the current window url for highlighting purpose. |
+
+### Paginated collection paginator
+
+Use `page.paginator` to acceess the fields below.
+
+| Field | Description |
+| --- | --- |
+| total_pages | Total number of pages of the paginated collection. |
+| pages | All the pages in the collection. |
+| page_num_zero_index | Current page's 0-index page number. |
+| page_num_one_index | Current page's 1-index page number. |
+| page_num_label | Current page's page number label. |
+| collection | Current page's collection. |
+| collection_type | Current page's collection type. |
+| current_page | Current page. |
+| current_page_path | Current page full url. Can be used to match the current window url for highlighting purpose. |
+| previous_page | Previous page. |
+| previous_page_path | Previous page full url. Can be used to generate navigation link. |
+| next_page | Next page. |
+| next_page_path | Next page full url. Can be used to generate navigation link. |
+
+An example of the paginated collection page layout `books_pagination`:
+
+```html
+---
+layout: default
+---
+<h1>Books</h1>
+<div class="collection">
+{% raw %}
+{% for book in page.paginator.collection %}
+  <div class="item">
+    <div class="title">
+      <span>{{ book.title }}</span>
+    </div>
+    <p>{{ book.excerpt }}</p>
+  </div>
+{% endfor %}
+</div>
+
+{% if page.paginator.total_pages > 1 %}
+<div class="pagination">
+  <ul class="pager">
+    {% if page.paginator.previous_page %}
+    <li class="previous">
+      <a href="{{ page.paginator.previous_page_path }}"><i class="fa-solid fa-arrow-left"></i> Newer {{ page.paginator.collection_type | capitalize }}</a>
+    </li>
+    {% endif %}
+    {% if page.paginator.next_page %}
+    <li class="next">
+      <a href="{{ page.paginator.next_page_path }}">Older {{ page.paginator.collection_type | capitalize }} <i class="fa-solid fa-arrow-right"></i></a>
+    </li>
+    {% endif %}
+  </ul>
+</div>
+{% endif %}
+{% endraw %}
+```
+
+The resulting index pages using the example configuration and layout are as such:
+
+### Root page
+
+Generated at: `_site/books.html`.
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>Books</title>
+  </head>
+  <body>
+    <div class="container">
+      <h1>Books</h1>
+      <div class="collection">
+        <div class="item">
+          <div class="title">
+            <span>Harry Potter 7</span>
+          </div>
+          <p>This is the final book in the Harry Potter series.</p>
+        </div>
+
+        <div class="item">
+          <div class="title">
+            <span>Harry Potter 6</span>
+          </div>
+          <p>This is the sixth book in the Harry Potter series.</p>
+        </div>
+
+        <div class="item">
+          <div class="title">
+            <span>Harry Potter 5</span>
+          </div>
+          <p>This is the fifth book in the Harry Potter series.</p>
+        </div>
+      </div>
+
+      <div class="pagination">
+        <ul class="pager">
+          <li class="next">
+            <a href="/books/2/index.html">Older Books <i class="fa-solid fa-arrow-right"></i></a>
+          </li>
+        </ul>
+      </div>
+    </div>
+  </body>
+</html>
+```
+
+### Next page
+
+Generated at: `_site/books/2/index.html`.
+
+Note: Header elements omitted for clarity.
+
+```html
+<div class="container">
+  <h1>Books</h1>
+  <div class="collection">
+    <div class="item">
+      <div class="title">
+        <span>Harry Potter 4</span>
+      </div>
+      <p>This is the fourth book in the Harry Potter series.</p>
+    </div>
+
+    <div class="item">
+      <div class="title">
+        <span>Harry Potter 3</span>
+      </div>
+      <p>This is the third book in the Harry Potter series.</p>
+    </div>
+
+    <div class="item">
+      <div class="title">
+        <span>Harry Potter 2</span>
+      </div>
+      <p>This is the second book in the Harry Potter series.</p>
+    </div>
+  </div>
+
+  <div class="pagination">
+    <ul class="pager">
+      <li class="previous">
+        <a href="/books.html"><i class="fa-solid fa-arrow-left"></i> Newer Books</a>
+      </li>
+      <li class="next">
+        <a href="/books/3/index.html">Older Books <i class="fa-solid fa-arrow-right"></i></a>
+      </li>
+    </ul>
+  </div>
+</div>
+```
+
+### Last page
+
+Generated at: `_site/books/3/index.html`.
+
+Note: Header elements omitted for clarity.
+
+```html
+<div class="container">
+  <h1>Books</h1>
+  <div class="collection">
+    <div class="item">
+      <div class="title">
+        <span>Harry Potter 1</span>
+      </div>
+      <p>This is the first book in the Harry Potter series.</p>
+    </div>
+  </div>
+
+  <div class="pagination">
+    <ul class="pager">
+      <li class="previous">
+        <a href="/books/2/index.html"><i class="fa-solid fa-arrow-left"></i> Newer Books</a>
+      </li>
+    </ul>
+  </div>
+</div>
+```
+
+### Individual page paginator
+
+Use `page.paginator` to access the fields below.
+
+| Field | Description |
+| --- | --- |
+| collection_type | Current page's collection type. |
+| current_page | Current page. |
+| current_page_path | Current page full url. Can be used to match the current window url for highlighting purpose. |
+| previous_page | Previous page. |
+| previous_page_path | Previous page full url. Can be used to generate navigation link. |
+| next_page | Next page. |
+| next_page_path | Next page full url. Can be used to generate navigation link. |
+
+An example of the individual page layout `book`:
+
+```html
+---
+layout: default
+---
+<h1>{{ page.title }}</h1>
+{% raw %}
+<div class="title">
+  <span>{{ page.title }}</span>
+</div>
+<p>{{ content }}</p>
+
+{% if page.paginator %}
+<div class="pagination">
+  <ul class="pager">
+    {% if page.paginator.previous_page %}
+    <li class="previous">
+      <a href="{{ page.paginator.previous_page_path }}"><i class="fa-solid fa-arrow-left"></i> Previous Book</a>
+    </li>
+    {% endif %}
+    {% if page.paginator.next_page %}
+    <li class="next">
+      <a href="{{ page.paginator.next_page_path }}">Next Book <i class="fa-solid fa-arrow-right"></i></a>
+    </li>
+    {% endif %}
+  </ul>
+</div>
+{% endif %}
+{% endraw %}
+```
+
+The resulting page using the example configuration and layout are as such:
+
+### Individual page
+
+Generated at: `_site/books/book-1.html`
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>Books</title>
+  </head>
+  <body>
+    <div class="container">
+      <h1>Book 1</h1>
+      <div class="title">
+        <span>Book 1</span>
+      </div>
+      <p>This is book 1.</p>
+
+      <div class="pagination">
+        <ul class="pager">
+          <li class="next">
+            <a href="/books/book-2.html">Next Book <i class="fa-solid fa-arrow-right"></i></a>
+          </li>
+        </ul>
+      </div>
+    </div>
+  </body>
+</html>
+```
+
+## Contributing
+
+Contribution to the gem is very much welcome!
+
+1. Fork it (https://github.com/coffeebrewapps/coffeebrew_jekyll_paginate/fork).
+2. Create your feature branch (`git checkout -b my-new-feature`).
+3. Make sure you have setup the repo correctly so that you can run RSpec and Rubocop on your changes. Read more under the [Development](#development) section.
+4. Commit your changes (`git commit -am 'Add some feature'`).
+5. If you have added something that is worth mentioning in the README, please also update the README.md accordingly and commit the changes.
+6. Push to the branch (`git push origin my-new-feature`).
+7. Create a new Pull Request.
+
+The repo owner will try to respond to a new PR as soon as possible.
+
+## Development
+
+We want to provide a robust gem as much as possible for the users, so writing test cases will be required for any new
+feature.
+
+If you are contributing to the gem, please make sure you have setup your development environment correctly so that
+RSpec and Rubocop can run properly.
+
+1. After forking the repo, go into the repo directory (`cd coffeebrew_jekyll_paginate/`).
+2. Make sure you have the correct Ruby version installed. This gem requires Ruby >= 2.7.0.
+3. Once you have the correct Ruby version, install the development dependencies (`bundle install`).
+4. To test that you have everything installed correctly, run the test cases (`bundle exec rspec`).
+5. You should see all test cases pass successfully.
+
+### Source directory structure
+
+All the gem logic lives in the `/lib` directory:
+
+```bash
+lib
+├── coffeebrew_jekyll_paginate
+│   ├── config.yml
+│   ├── generator.rb
+│   ├── individual_paginator.rb
+│   ├── page.rb
+│   ├── page_drop.rb
+│   ├── paginator.rb
+│   ├── validator.rb
+│   └── version.rb
+└── coffeebrew_jekyll_paginate.rb
+```
+
+The files that are currently in the repo:
+
+| File | Description |
+| --- | --- |
+| `lib/coffeebrew_jekyll_paginate/config.yml` | This contains the default configuration for the plugin to generate pagination. |
+| `lib/coffeebrew_jekyll_paginate/generator.rb` | This is the generator that reads the configuration and generate pagination. |
+| `lib/coffeebrew_jekyll_paginate/individual_paginator.rb` | This is the abstract model containing the pagination methods for individual pages. |
+| `lib/coffeebrew_jekyll_paginate/page.rb` | This is the abstract model of the paginated collection pages. |
+| `lib/coffeebrew_jekyll_paginate/page_drop.rb` | This is the page drop used by the paginator class so its methods can be used in Liquid template. |
+| `lib/coffeebrew_jekyll_paginate/paginator.rb` | This is the abstract model containing the pagination methods for paginated collection pages. |
+| `lib/coffeebrew_jekyll_paginate/validator.rb` | This validates the configuration. |
+| `lib/coffeebrew_jekyll_paginate/version.rb` | This contains the version number of the gem. |
+| `lib/coffeebrew_jekyll_paginate.rb` | This is the entry point of the gem, and it loads the dependencies. |
+
+### Test cases directory structure
+
+All the test cases and fixtures live in the `/spec` directory:
+
+Note: Some files have been omitted for clarity.
+
+```bash
+spec
+├── coffeebrew_jekyll_paginate_spec.rb
+├── dest
+├── fixtures
+│   ├── _books
+│   │   ├── 1997-06-26-harry-potter-1.md
+│   │   ├── 1998-07-02-harry-potter-2.md
+│   │   ├── 1999-07-08-harry-potter-3.md
+│   │   ├── 2000-07-08-harry-potter-4.md
+│   │   ├── 2003-06-21-harry-potter-5.md
+│   │   ├── 2005-07-16-harry-potter-6.md
+│   │   └── 2007-07-21-harry-potter-7.md
+│   ├── _layouts
+│   │   ├── book.html
+│   │   ├── default.html
+│   │   ├── paginated_books.html
+│   │   ├── paginated_posts.html
+│   │   └── post.html
+│   ├── _posts
+│   │   ├── 2021-03-12-test-post-1.md
+│   │   ├── 2021-03-28-test-post-2.md
+│   │   ├── 2021-05-03-test-post-3.md
+│   │   ├── 2021-05-03-test-post-4.md
+│   │   ├── 2022-01-27-test-post-5.md
+│   │   ├── 2022-03-12-test-post-6.md
+│   │   ├── 2022-11-23-test-post-7.md
+│   │   └── 2023-02-21-test-post-8.md
+│   └── _config.yml
+├── scenarios
+│   ├── default
+│   │   ├── _site
+│   │   │   ├── books
+│   │   │   │   ├── 1
+│   │   │   │   │   └── index.html
+│   │   │   │   ├── 2
+│   │   │   │   │   └── index.html
+│   │   │   │   ├── 1997-06-26-harry-potter-1.html
+│   │   │   │   ├── 1998-07-02-harry-potter-2.html
+│   │   │   │   ├── 1999-07-08-harry-potter-3.html
+│   │   │   │   ├── 2000-07-08-harry-potter-4.html
+│   │   │   │   ├── 2003-06-21-harry-potter-5.html
+│   │   │   │   ├── 2005-07-16-harry-potter-6.html
+│   │   │   │   └── 2007-07-21-harry-potter-7.html
+│   │   │   └── posts
+│   │   │       ├── 1
+│   │   │       │   └── index.html
+│   │   │       ├── 2
+│   │   │       │   └── index.html
+│   │   │       ├── 2021-03-12-test-post-1.html
+│   │   │       ├── 2021-03-28-test-post-2.html
+│   │   │       ├── 2021-05-03-test-post-3.html
+│   │   │       ├── 2021-05-03-test-post-4.html
+│   │   │       ├── 2022-01-27-test-post-5.html
+│   │   │       ├── 2022-03-12-test-post-6.html
+│   │   │       ├── 2022-11-23-test-post-7.html
+│   │   │       └── 2023-02-21-test-post-8.html
+│   │   └── context.rb
+│   └── invalid_config_keys
+│       └── context.rb
+└── spec_helper.rb
+```
+
+The files that are currently in the repo:
+
+| File | Description |
+| --- | --- |
+| `spec/coffeebrew_jekyll_paginate_spec.rb` | This is the main RSpec file to be executed. It contains all the contexts of various scenarios. |
+| `spec/dest/` | This directory is where generated files are located. It will be deleted immediately after each context is executed. |
+| `spec/fixtures/` | This directory follows the Jekyll site source structure and contains the minimal files required to generate the paginated pages. |
+| `spec/fixtures/_books` | This directory contains the test books, you can add more to it to test your new feature. |
+| `spec/fixtures/_posts` | This directory contains the test posts, you can add more to it to test your new feature. |
+| `spec/scenarios/` | This directory contains the expected files of various test scenarios. |
+| `spec/scenarios/<scenario>/` | This is the scenario name. |
+| `spec/scenarios/<scenario>/_site/` | This directory contains the expected paginated pages. |
+| `spec/scenarios/<scenario>/context.rb` | This is the file that sets up the context for the test case. |
+| `spec/spec_helper.rb` | This contains RSpec configuration and certain convenience methods for the main RSpec file. |
+
+### Writing test cases
+
+There is a certain convention to follow when writing new test scenarios. The recommendation is to use the rake tasks
+provided in the gem to generate the scenario files.
+
+For success scenarios, run:
+
+```bash
+bundle exec rake coffeebrew:jekyll:paginate:test:create_success[test_scenario]
+```
+
+This will generate a placeholder file and directory:
+
+```bash
+spec
+├── coffeebrew_jekyll_paginate_spec.rb
+├── scenarios
+│   └── test_scenario
+│       ├── _site
+│       └── context.rb
+└── spec_helper.rb
+```
+
+Where the `context.rb` file will be pre-populated:
+
+```ruby
+# frozen_string_literal: true
+
+CONTEXT_TEST_SCENARIO = "when using test_scenario config"
+
+RSpec.shared_context CONTEXT_TEST_SCENARIO do
+  let(:scenario) { "test_scenario" }
+  let(:overrides) {} # TODO: remove if unused
+  let(:generated_files) {} # TODO: remove if unused
+  let(:expected_files) do
+    [
+    ]
+  end
+end
+```
+
+For failure scenarios, run:
+
+```bash
+bundle exec rake coffeebrew:jekyll:paginate:test:create_failure[test_scenario]
+```
+
+This will generate a placeholder file and directory:
+
+```bash
+spec
+├── coffeebrew_jekyll_paginate_spec.rb
+├── scenarios
+│   └── test_scenario
+│       └── context.rb
+└── spec_helper.rb
+```
+
+Where the `context.rb` file will be pre-populated:
+
+```ruby
+# frozen_string_literal: true
+
+CONTEXT_TEST_SCENARIO = "when using test_scenario config"
+
+RSpec.shared_context CONTEXT_TEST_SCENARIO do
+  let(:scenario) { "test_scenario" }
+  let(:generated_files) { [] }
+  let(:expected_files) { [] }
+  let(:overrides) do
+    {
+    }
+  end
+
+  let(:expected_errors) do
+    [
+    ]
+  end
+end
+```
+
+If you do write other test cases that are not asserting the generated files like above, you can initiate your
+convention. The repo owner will evaluate the PR and accept the convention if it fits the repo existing convention, or
+will recommend an alternative if it doesn't.
+
+## License
+
+See the [LICENSE](LICENSE) file.

data/lib/coffeebrew_jekyll_paginate/config.yml

@@ -0,0 +1,13 @@
+coffeebrew_jekyll_paginate:
+  defaults:
+    individual_page_pagination: false
+    frontmatter_defaults_key: "paginated_%{collection_type}"
+    first_page_as_root:
+      enabled: false
+    permalink: /:collection_type/:page_num_one_index
+    index_page: "index"
+    per_page: 5
+    sort_field: "date"
+    sort_reverse: true
+    page_num_label: "%{page_num_one_index}"
+  collections: []

data/lib/coffeebrew_jekyll_paginate/generator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "./page"
+require_relative "./individual_paginator"
+require_relative "./paginator"
+require_relative "./validator"
+
+module Coffeebrew
+  module Jekyll
+    module Paginate
+      class Generator < ::Jekyll::Generator
+        safe true
+        priority :lowest
+
+        def generate(site)
+          @site = site
+
+          validate!
+
+          user_collections_config.each do |collection_type, options|
+            collection_options = add_collections_defaults(options)
+            process_collection(collection_type.to_sym, collection_options)
+          end
+        end
+
+        private
+
+        def validate!
+          validator = Coffeebrew::Jekyll::Paginate::Validator.new(@site, user_config)
+          validator.validate!
+        end
+
+        def process_collection(collection_type, options)
+          sort_field = options["sort_field"].to_sym
+          sort_reverse = options["sort_reverse"]
+          records = @site.collections[collection_type.to_s].docs
+          records.sort_by!(&sort_field)
+          records.reverse! if sort_reverse
+
+          individual_pagination = options["individual_page_pagination"]
+          generate_individual_page_paginator(collection_type, records) if individual_pagination
+
+          pages = generate_pages(collection_type, records, options)
+          return if pages.empty?
+
+          generate_paginators(collection_type, pages)
+        end
+
+        def generate_individual_page_paginator(collection_type, records)
+          records.each_with_index do |record, index|
+            prev_record = index.positive? ? records[index - 1] : nil
+            next_record = index < records.length ? records[index + 1] : nil
+            paginator = Paginate::IndividualPaginator.new(collection_type, prev_record, record, next_record)
+            record.data["paginator"] = paginator
+          end
+        end
+
+        def generate_pages(collection_type, records, options)
+          per_page = options["per_page"].to_i
+          first_page_as_root = options["first_page_as_root"]
+
+          records.each_slice(per_page).with_index.map do |page_records, page_num|
+            page_options = options.clone
+            if first_page_as_root["enabled"] && page_num.zero?
+              page_options["permalink"] = first_page_as_root["permalink"]
+              page_options["index_page"] = first_page_as_root["index_page"]
+            end
+            Paginate::Page.new(@site, page_options, collection_type, page_records, page_num)
+          end
+        end
+
+        def generate_paginators(collection_type, pages)
+          pages.each do |page|
+            paginator = Paginate::Paginator.new(pages, collection_type, page.page_num_zero_index)
+            page.paginator = paginator
+            @site.pages << page
+          end
+        end
+
+        def add_collections_defaults(user_options)
+          ::Jekyll::Utils.deep_merge_hashes(
+            default_defaults_config,
+            ::Jekyll::Utils.deep_merge_hashes(user_defaults_config, user_options)
+          )
+        end
+
+        def user_collections_config
+          @user_collections_config ||= user_config["collections"].to_h.transform_values(&:to_h)
+        end
+
+        def user_defaults_config
+          @user_defaults_config ||= user_config["defaults"].to_h
+        end
+
+        def user_config
+          @user_config ||= @site.config["coffeebrew_jekyll_paginate"].to_h
+        end
+
+        def default_defaults_config
+          @default_defaults_config ||= default_config.dig("coffeebrew_jekyll_paginate", "defaults").to_h
+        end
+
+        def default_config
+          @default_config ||= YAML.safe_load(File.read(default_config_path))
+        end
+
+        def default_config_path
+          @default_config_path ||= File.expand_path("config.yml", __dir__)
+        end
+      end
+    end
+  end
+end

data/lib/coffeebrew_jekyll_paginate/individual_paginator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "./page_drop"
+
+module Coffeebrew
+  module Jekyll
+    module Paginate
+      class IndividualPaginator
+        attr_reader :collection_type,
+                    :current_page, :current_page_path,
+                    :previous_page, :previous_page_path,
+                    :next_page, :next_page_path
+
+        def initialize(collection_type, previous_page, current_page, next_page)
+          @collection_type = collection_type
+          @current_page = current_page
+          @current_page_path = full_url(@current_page)
+          @previous_page = previous_page
+          @previous_page_path = full_url(@previous_page)
+          @next_page = next_page
+          @next_page_path = full_url(@next_page)
+        end
+
+        def data
+          @data ||= {
+            "collection_type" => collection_type,
+            "current_page" => current_page,
+            "current_page_path" => current_page_path,
+            "previous_page" => previous_page,
+            "previous_page_path" => previous_page_path,
+            "next_page" => next_page,
+            "next_page_path" => next_page_path
+          }
+        end
+
+        def to_liquid
+          @to_liquid ||= Paginate::PageDrop.new(self)
+        end
+
+        private
+
+        def full_url(page)
+          return "" if page.nil?
+
+          page.url
+        end
+      end
+    end
+  end
+end

data/lib/coffeebrew_jekyll_paginate/page.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Coffeebrew
+  module Jekyll
+    module Paginate
+      class Page < ::Jekyll::Page
+        attr_reader :paginator, :collection_type, :collection,
+                    :page_num_zero_index, :page_num_one_index
+
+        def initialize(site, config, collection_type, collection, page_num_zero_index) # rubocop:disable Lint/MissingSuper
+          @site = site
+          @config = config
+          @collection_type = collection_type
+          @collection = collection
+          @page_num_zero_index = page_num_zero_index
+          @page_num_one_index = page_num_zero_index.to_i + 1
+
+          @base = site.source
+          @ext = ".html"
+
+          build_data
+        end
+
+        def paginator=(paginator)
+          @paginator = paginator
+          @data["paginator"] = paginator
+
+          data.default_proc = proc do |_, key|
+            site.frontmatter_defaults.find(relative_path, frontmatter_defaults_key, key)
+          end
+        end
+
+        def frontmatter_defaults_key
+          @frontmatter_defaults_key ||= format(@config["frontmatter_defaults_key"], collection_type: collection_type)
+        end
+
+        def basename
+          @basename ||= ::Jekyll::URL.new(template: nil,
+                                          placeholders: basename_placeholders,
+                                          permalink: @config["index_page"])
+                                     .to_s
+        end
+
+        def name
+          @name ||= "#{basename}#{ext}"
+        end
+
+        def dir
+          @dir ||= ::Jekyll::URL.new(template: nil,
+                                     placeholders: page_dir_placeholders,
+                                     permalink: @config["permalink"])
+                                .to_s
+        end
+
+        def page_dir_placeholders
+          @page_dir_placeholders ||= {
+            collection_type: collection_type.to_s,
+            page_num_zero_index: page_num_zero_index.to_s,
+            page_num_one_index: page_num_one_index.to_s,
+            basename: basename,
+            output_ext: output_ext
+          }
+        end
+
+        def basename_placeholders
+          @basename_placeholders ||= {
+            collection_type: collection_type.to_s,
+            page_num_zero_index: page_num_zero_index.to_s,
+            page_num_one_index: page_num_one_index.to_s
+          }
+        end
+
+        def url_placeholders
+          {
+            path: dir,
+            basename: basename,
+            output_ext: output_ext
+          }
+        end
+
+        def page_num_label
+          @page_num_label ||= format(@config["page_num_label"],
+                                     page_num_zero_index: page_num_zero_index, page_num_one_index: page_num_one_index)
+        end
+
+        def title
+          @title ||= collection_type.capitalize
+        end
+
+        def full_url
+          @full_url ||= [dir, name].join("/").squeeze("/")
+        end
+
+        private
+
+        def build_data
+          @data = {
+            "title" => title,
+            "collection" => collection,
+            "collection_type" => collection_type,
+            "page_num_zero_index" => page_num_zero_index,
+            "page_num_one_index" => page_num_one_index,
+            "page_num_label" => page_num_label,
+            "full_url" => full_url
+          }
+        end
+      end
+    end
+  end
+end

data/lib/coffeebrew_jekyll_paginate/page_drop.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Coffeebrew
+  module Jekyll
+    module Paginate
+      class PageDrop < ::Jekyll::Drops::Drop
+        extend Forwardable
+
+        mutable false
+
+        def_delegators :@obj, :posts, :type, :title, :date, :name, :path, :url, :permalink
+        def_delegator :@obj, :data, :fallback_data
+      end
+    end
+  end
+end

data/lib/coffeebrew_jekyll_paginate/paginator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "./page_drop"
+
+module Coffeebrew
+  module Jekyll
+    module Paginate
+      class Paginator
+        attr_reader :total_pages, :pages,
+                    :page_num_zero_index, :page_num_one_index, :page_num_label,
+                    :collection, :collection_type,
+                    :current_page, :current_page_path,
+                    :previous_page, :previous_page_path,
+                    :next_page, :next_page_path
+
+        def initialize(pages, collection_type, page_num_zero_index = 0)
+          @total_pages = pages.size
+          @pages = pages
+          @page_num_zero_index = page_num_zero_index
+          @collection_type = collection_type
+
+          set_current_page
+          set_prev_page
+          set_next_page
+        end
+
+        def data # rubocop:disable Metrics/MethodLength
+          @data ||= {
+            "total_pages" => total_pages,
+            "pages" => pages,
+            "page_num_zero_index" => page_num_zero_index,
+            "page_num_one_index" => page_num_one_index,
+            "page_num_label" => page_num_label,
+            "collection" => collection,
+            "collection_type" => collection_type,
+            "current_page" => current_page,
+            "current_page_path" => current_page_path,
+            "previous_page" => previous_page,
+            "previous_page_path" => previous_page_path,
+            "next_page" => next_page,
+            "next_page_path" => next_page_path
+          }
+        end
+
+        def to_liquid
+          @to_liquid ||= Paginate::PageDrop.new(self)
+        end
+
+        private
+
+        def set_current_page
+          @current_page = pages[page_num_zero_index]
+          @current_page_path = full_url(@current_page)
+
+          @collection = current_page&.collection || []
+          @page_num_one_index = @current_page&.page_num_one_index
+          @page_num_label = @current_page&.page_num_label
+        end
+
+        def set_prev_page
+          return if page_num_zero_index.zero?
+
+          @previous_page = pages[page_num_zero_index - 1]
+          @previous_page_path = full_url(@previous_page)
+        end
+
+        def set_next_page
+          return unless page_num_zero_index < total_pages - 1
+
+          @next_page = pages[page_num_zero_index + 1]
+          @next_page_path = full_url(@next_page)
+        end
+
+        def full_url(page)
+          return "" if page.nil?
+
+          page.full_url
+        end
+      end
+    end
+  end
+end

data/lib/coffeebrew_jekyll_paginate/validator.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Coffeebrew
+  module Jekyll
+    module Paginate
+      class Validator
+        ROOT_KEY = "coffeebrew_jekyll_paginate"
+        COLLECTIONS_KEY = "collections"
+        DEFAULTS_KEY = "defaults"
+
+        ALLOWED_ROOT_KEYS = [
+          COLLECTIONS_KEY,
+          DEFAULTS_KEY
+        ].freeze
+
+        ALLOWED_CONFIG_KEYS = {
+          "frontmatter_defaults_key" => [],
+          "individual_page_pagination" => [true, false],
+          "first_page_as_root" => {
+            "enabled" => [true, false],
+            "permalink" => [],
+            "index_page" => []
+          },
+          "permalink" => [],
+          "index_page" => [],
+          "per_page" => [],
+          "sort_field" => [],
+          "sort_reverse" => [true, false],
+          "page_num_label" => []
+        }.freeze
+
+        def initialize(site, config)
+          @site = site
+          @config = config
+          @errors = []
+        end
+
+        def validate!
+          parse_root
+          parse_defaults
+          parse_collection_keys
+          parse_collections_config
+
+          return if @errors.empty?
+
+          ::Jekyll.logger.error "'coffeebrew_jekyll_paginate' config is set incorrectly."
+          ::Jekyll.logger.error "Errors:", @errors
+
+          raise ::Jekyll::Errors::InvalidConfigurationError, "'coffeebrew_jekyll_paginate' config is set incorrectly."
+        end
+
+        private
+
+        def parse_root
+          not_allowed_keys = @config.keys.reject do |key|
+            ALLOWED_ROOT_KEYS.include?(key)
+          end
+          return if not_allowed_keys.empty?
+
+          @errors << { key: ROOT_KEY, expected: ALLOWED_ROOT_KEYS, got: not_allowed_keys }
+        end
+
+        def defaults_config
+          @defaults_config ||= @config[DEFAULTS_KEY].to_h
+        end
+
+        def parse_defaults
+          parse(defaults_config, ALLOWED_CONFIG_KEYS, ["#{ROOT_KEY}.#{DEFAULTS_KEY}"])
+        end
+
+        def configured_collections
+          @configured_collections ||= collections_config.keys.sort
+        end
+
+        def allowed_collections
+          @allowed_collections ||= @site.collections.keys
+        end
+
+        def parse_collection_keys
+          not_allowed_collections = configured_collections.reject do |configured_collection|
+            allowed_collections.include?(configured_collection)
+          end
+          return if not_allowed_collections.empty?
+
+          @errors << {
+            key: "#{ROOT_KEY}.collections",
+            expected: allowed_collections,
+            got: not_allowed_collections
+          }
+        end
+
+        def collections_config
+          @collections_config ||= @config[COLLECTIONS_KEY].to_h.transform_values(&:to_h)
+        end
+
+        def parse_collections_config
+          collections_config.each do |collection_type, options|
+            parse(options, ALLOWED_CONFIG_KEYS, ["#{ROOT_KEY}.#{COLLECTIONS_KEY}.#{collection_type}"])
+          end
+        end
+
+        def parse(hash, allowed_keys, parent_key)
+          hash.each do |key, configured_value|
+            allowed_values = allowed_keys[key]
+            new_parent_key = parent_key + [key]
+
+            next if configured_in_allowed_values?(allowed_values, configured_value)
+
+            if same_hash_type?(allowed_values, configured_value)
+              next parse(configured_value, allowed_values, new_parent_key)
+            end
+
+            add_error(new_parent_key, allowed_values, configured_value)
+          end
+        end
+
+        def same_hash_type?(allowed_values, configured_value)
+          allowed_values.is_a?(Hash) && configured_value.is_a?(Hash)
+        end
+
+        def primitive?(value)
+          value.nil? || value.is_a?(String) || value.is_a?(Numeric) || value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        end
+
+        def configured_in_allowed_values?(allowed_values, configured_value)
+          allowed_values.is_a?(Array) && primitive?(configured_value) &&
+            (allowed_values.empty? || allowed_values.include?(configured_value))
+        end
+
+        def add_error(parent_key, allowed_values, configured_value)
+          @errors << { key: parent_key.join("."), expected: allowed_values, got: configured_value }
+        end
+      end
+    end
+  end
+end

data/lib/coffeebrew_jekyll_paginate/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Coffeebrew
+  module Jekyll
+    module Paginate
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/coffeebrew_jekyll_paginate.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require "coffeebrew_jekyll_paginate/generator"
+
+module Coffeebrew
+  module Jekyll
+    module Paginate
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: coffeebrew_jekyll_paginate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Coffee Brew Apps
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-04-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: A Jekyll plugin to generate pagination for site collections
+email:
+- coffeebrewapps@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
+- LICENSE
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/coffeebrew_jekyll_paginate.rb
+- lib/coffeebrew_jekyll_paginate/config.yml
+- lib/coffeebrew_jekyll_paginate/generator.rb
+- lib/coffeebrew_jekyll_paginate/individual_paginator.rb
+- lib/coffeebrew_jekyll_paginate/page.rb
+- lib/coffeebrew_jekyll_paginate/page_drop.rb
+- lib/coffeebrew_jekyll_paginate/paginator.rb
+- lib/coffeebrew_jekyll_paginate/validator.rb
+- lib/coffeebrew_jekyll_paginate/version.rb
+homepage: https://coffeebrewapps.com/coffeebrew_jekyll_paginate
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib/coffeebrew_jekyll_paginate
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: A Jekyll plugin to generate pagination for site collections
+test_files: []