coffeebrew_jekyll_archives 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 43b2a4c983a82213e4a7c864e991616436db32853816d4c6fb3ba160b190d01b
+  data.tar.gz: 7547594cf6862c22b962435fdee631e5890609fb2b377a1ac42540e01a7a49fd
+SHA512:
+  metadata.gz: cee0c42d0a3177f017bc335d1b0156372db4590c76f81122f2d9d6a1838f52317cdc2c9f5acbbbf7d36379904970c18e3c94db72ca01f21602fabb89593cb7ef
+  data.tar.gz: ffdccf2bc5624e70802c2c6b8fbdd0d3402846f4030a8493447182c22d0bbe177a8cab0808dab9ce57d0a818426b5bd38b278c131cac243578f37732722c2112

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Version 0.2.0
+
+[View version doc](https://github.com/coffeebrewapps/coffeebrew_jekyll_archives/blob/v0.2.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,626 @@
+# Jekyll Archives Plugin
+
+A Jekyll plugin to generate site post archives.
+
+[![Continuous Integration](https://github.com/coffeebrewapps/coffeebrew_jekyll_archives/actions/workflows/ruby.yml/badge.svg)](https://github.com/coffeebrewapps/coffeebrew_jekyll_archives/actions/workflows/ruby.yml) [![Gem Version](https://badge.fury.io/rb/coffeebrew_jekyll_archives.svg)](https://badge.fury.io/rb/coffeebrew_jekyll_archives)
+
+## Installation
+
+Add this line to your site's Gemfile:
+
+```ruby
+gem 'coffeebrew_jekyll_archives'
+```
+
+And then add this line to your site's `_config.yml`:
+
+```yml
+plugins:
+  - coffeebrew_jekyll_archives
+```
+
+Upon building the Jekyll site, the plugin will automatically generate the archive indexes using the following default
+configuration:
+
+```yml
+---
+archives:
+  navigation:
+    data: "navigation"
+    name: "Archives"
+    before:
+    after:
+  depths: 3
+  title_format:
+    root:
+      type: "string"
+      style: "/"
+    year:
+      type: "date"
+      style: "%Y"
+    month:
+      type: "date"
+      style: "%b, %Y"
+    day:
+      type: "date"
+      style: "%d %b, %Y"
+  root_dir: "/"
+  root_basename: "archives"
+  index_root: "/archives"
+  index_basename: "index"
+  permalink:
+    root: "/:root_dir"
+    year: "/:root_dir/:index_root/:year"
+    month: "/:root_dir/:index_root/:year/:month"
+    day: "/:root_dir/:index_root/:year/:month/:day"
+```
+
+An example of the generated directory structure is as such:
+
+```bash
+_site/
+├── archives
+│   └── 2023
+│       ├── 03
+│       │   ├── 30
+│       │   │   └── index.html
+│       │   └── index.html
+│       └── index.html
+├── archives.html
+└── index.html
+```
+
+## Configuration
+
+You can override any of the default configuration values above. The plugin will perform a simple validation on your
+overrides according to these rules:
+
+### Navigation config
+
+This tells the plugin how to generate navigation menu.
+
+| Key | Allowed Value(s) | Default | Remark |
+| --- | --- | --- | --- |
+| data | String | navigation | This tells the plugin where in `site.data[]` to get the navigation data. Usually this would be set in `site.data["navigation"]`. |
+| name | String | Archives | This is the name rendered in the navigation menu item. |
+| before | String | nil | This tells the plugin before which existing menu item to insert the archives' root index menu item. |
+| after | String | nil | This tells the plugin after which existing menu item to insert the archives' root index menu item. |
+
+When `before` and `after` are `nil`, the archives' root index menu item will be appended last.
+
+If both `before` and `after` are configured, `before` config will be used and `after` will be ignored.
+
+### Depths config
+
+This tells the plugin what indexes to generate.
+
+There are 3 levels of depths:
+
+| Level | Description |
+| --- | --- |
+| 1 | Generate yearly index only |
+| 2 | Generate yearly and monthly indexes |
+| 3 | Generate yearly, monthly and daily indexes |
+
+### Title format config
+
+This tells the plugin what is the format of the title to be used for the index entries.
+
+There are 4 titles that can be generated:
+
+| Level | Description |
+| --- | --- |
+| root | This will be used for the root index entry |
+| year | This will be used for the yearly index entries |
+| month | This will be used for the monthly index entries |
+| day | This will be used for the daily index entries |
+
+For each title format, you can use one of these types:
+
+| Type | Description |
+| --- | --- |
+| string | A string that uses format syntax and use available variables: year, month, day, eg. `Archive of %{year}-%{month}-%{day}` will be interpreted as `Archive of 2023-03-12` |
+| date | A string that strictly uses Ruby date identifiers, the plugin will call `date.strftime()` on the format string, eg. `%d %b, %Y` will be interpreted as `12 Mar, 2023` |
+
+### Directory and path config
+
+This tells the plugin how to create the directory structure and index page file name.
+
+| Key | Allowed Value(s) | Default | Remark |
+| --- | --- | --- | --- |
+| root_dir | String | / | This tells the plugin what is the root directory to create the root index page. |
+| root_basename | String | archives | This tells the plugin what is the root index page file name, with `.html` as the extension. |
+| index_root | String | /archives | This tells the plugin what is the root directory for the yearly/monthly/daily index pages to be generated. |
+| index_basename | String | index | This tells the plugin what is the file name to use for the yearly/monthly/daily index pages, with `.html` as the extension. |
+
+### Permalink config
+
+This tells the plugin how to create the directory structure of the yearly/monthly/daily index pages, and the permalink
+for the index pages will follow the directory structure.
+
+There are 4 levels of pages that can be generated:
+
+| Level | Description |
+| --- | --- |
+| root | This will be used for the root index entry |
+| year | This will be used for the yearly index entries |
+| month | This will be used for the monthly index entries |
+| day | This will be used for the daily index entries |
+
+A few placeholders are available to be used in the permalink:
+
+| Field | Description |
+| --- | --- |
+| root_dir | This will be the root directory where the root index page is created. |
+| index_root | This will be the root directory where the yearly/monthly/daily index pages are created. |
+| year | This will be the current year of the current index page. If the current page is the root index, then `year` will always be `0001`. |
+| month | This will be the current month of the current index page. If the current page is a yearly index, then `month` will always be `01`. |
+| day | This will be the current day of the current index page. If the current page is a yearly or monthly index, then `day` will always be `01`. |
+
+### Validation
+
+If the config overrides have invalid structure, keys or values, the plugin will raise a
+`Jekyll::Errors::InvalidConfigurationError` during build.
+
+## Layout
+
+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`:
+
+```yml
+---
+defaults:
+  - scope:
+      type: "archives"
+    values:
+      layout: "archive"
+      permalink: /:path/:basename:output_ext
+```
+
+In addition to Jekyll's default page data, you can also use the page data generated by the plugin in the layout:
+
+| Field | Description |
+| --- | --- |
+| dir | The current index page directory.  |
+| sub_pages | The current index page's sub-pages according to the hierarchy of: 1) root, 2) yearly, 3) monthly, 4) daily. If the current page is the daily index page, then there will be no sub-pages. |
+| root | The root index page absolute url. This is useful if you need to highlight the archives' root navigation menu item while displaying the nested index pages. |
+| ancestors | The ancestors of the current page. This is useful if you need to render a tree view of the ancestor pages relative to the current page. |
+| parent | The immediate parent of the current page. |
+| collection | The posts collection under the current index page, eg. if the current page is a monthly index page, then all the current month's posts will be available. |
+| title | The title generated for the current page according to the `title_format` config. |
+| year | The current year of the current index page. If the current page is the root index, then `year` will always be `0001`. |
+| month | The current month of the current index page. If the current page is a yearly index, then `month` will always be `01`. |
+| day | The current day of the current index page. If the current page is a yearly or monthly index, then `day` will always be `01`. |
+
+An example of a layout that is used by the plugin's test cases:
+
+```html
+---
+layout: default
+---
+<h1>Archives of {{ page.title }}</h1>
+<div class="archives">
+  {% for ancestor in page.ancestors %}
+    <ul>
+      <li>
+        <i class="fa-solid fa-calendar-days"></i>
+        <a href="{{ ancestor.url }}">{{ ancestor.title }}</a>
+      </li>
+  {% endfor %}
+      <ul>
+        <li>
+          <i class="fa-solid fa-calendar-days"></i>
+          <a href="{{ page.url }}">{{ page.title }}</a>
+        </li>
+        {% if page.sub_pages.size > 0 %}
+          <ul>
+            {% for sub_page in page.sub_pages %}
+              <li>
+                <i class="fa-solid fa-calendar-days"></i>
+                <a href="{{ sub_page.url }}">{{ sub_page.title }}</a>
+              </li>
+            {% endfor %}
+          </ul>
+        {% else %}
+          <ul>
+            {% for item in page.collection %}
+              <li>
+                <i class="fa-solid fa-file"></i>
+                <a href="{{ item.url }}">{{ item.date | date: "%d %b, %Y" }} - {{ item.title }}</a>
+              </li>
+            {% endfor %}
+          </ul>
+        {% endif %}
+      </ul>
+  {% for ancestor in page.ancestors %}
+    </ul>
+  {% endfor %}
+</div>
+```
+
+The resulting index pages are as such:
+
+### Root
+
+Generated at: `_site/archives.html`.
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>/</title>
+  </head>
+  <body>
+    <nav>
+      <a href="/">Home</a>
+      <a href="/about.html">About</a>
+      <a href="/articles.html">Articles</a>
+      <a href="/projects.html">Projects</a>
+      <a href="/archives.html">Archives</a>
+    </nav>
+
+    <div class="container">
+      <h1>Archives of /</h1>
+      <div class="archives">
+        <ul>
+          <li>
+            <i class="fa-solid fa-calendar-days"></i>
+            <a href="/archives.html">/</a>
+          </li>
+          <ul>
+            <li>
+              <i class="fa-solid fa-calendar-days"></i>
+              <a href="/archives/2021/index.html">2021</a>
+            </li>
+            <li>
+              <i class="fa-solid fa-calendar-days"></i>
+              <a href="/archives/2022/index.html">2022</a>
+            </li>
+            <li>
+              <i class="fa-solid fa-calendar-days"></i>
+              <a href="/archives/2023/index.html">2023</a>
+            </li>
+          </ul>
+        </ul>
+      </div>
+    </div>
+  </body>
+</html>
+```
+
+### Yearly index
+
+Generated at: `_site/2021/index.html` for the year of 2021.
+
+Note: Header and navigation elements omitted for clarity.
+
+```html
+<div class="container">
+  <h1>Archives of 2021</h1>
+  <div class="archives">
+    <ul>
+      <li>
+        <i class="fa-solid fa-calendar-days"></i>
+        <a href="/archives.html">/</a>
+      </li>
+      <ul>
+        <li>
+          <i class="fa-solid fa-calendar-days"></i>
+          <a href="/archives/2021/index.html">2021</a>
+        </li>
+        <ul>
+          <li>
+            <i class="fa-solid fa-calendar-days"></i>
+            <a href="/archives/2021/03/index.html">Mar, 2021</a>
+          </li>
+          <li>
+            <i class="fa-solid fa-calendar-days"></i>
+            <a href="/archives/2021/05/index.html">May, 2021</a>
+          </li>
+        </ul>
+      </ul>
+    </ul>
+  </div>
+</div>
+```
+
+### Monthly index
+
+Generated at: `_site/2021/03/index.html` for the month of March 2021.
+
+Note: Header and navigation elements omitted for clarity.
+
+```html
+<div class="container">
+  <h1>Archives of Mar, 2021</h1>
+  <div class="archives">
+    <ul>
+      <li>
+        <i class="fa-solid fa-calendar-days"></i>
+        <a href="/archives.html">/</a>
+      </li>
+      <ul>
+        <li>
+          <i class="fa-solid fa-calendar-days"></i>
+          <a href="/archives/2021/index.html">2021</a>
+        </li>
+        <ul>
+          <li>
+            <i class="fa-solid fa-calendar-days"></i>
+            <a href="/archives/2021/03/index.html">Mar, 2021</a>
+          </li>
+          <ul>
+            <li>
+              <i class="fa-solid fa-calendar-days"></i>
+              <a href="/archives/2021/03/12/index.html">12 Mar, 2021</a>
+            </li>
+            <li>
+              <i class="fa-solid fa-calendar-days"></i>
+              <a href="/archives/2021/03/28/index.html">28 Mar, 2021</a>
+            </li>
+          </ul>
+        </ul>
+      </ul>
+    </ul>
+  </div>
+</div>
+```
+
+### Daily index
+
+Generated at: `_site/2021/03/12/index.html` for the day of 12 March 2021.
+
+Note: Header and navigation elements omitted for clarity.
+
+```html
+<div class="container">
+  <h1>Archives of 12 Mar, 2021</h1>
+  <div class="archives">
+    <ul>
+      <li>
+        <i class="fa-solid fa-calendar-days"></i>
+        <a href="/archives.html">/</a>
+      </li>
+      <ul>
+        <li>
+          <i class="fa-solid fa-calendar-days"></i>
+          <a href="/archives/2021/index.html">2021</a>
+        </li>
+        <ul>
+          <li>
+            <i class="fa-solid fa-calendar-days"></i>
+            <a href="/archives/2021/03/index.html">Mar, 2021</a>
+          </li>
+          <ul>
+            <li>
+              <i class="fa-solid fa-calendar-days"></i>
+              <a href="/archives/2021/03/12/index.html">12 Mar, 2021</a>
+            </li>
+            <ul>
+              <li>
+                <i class="fa-solid fa-file"></i>
+                <a href="/2021/03/12/test-post-1.html">12 Mar, 2021 - This is test post 1</a>
+              </li>
+            </ul>
+          </ul>
+        </ul>
+      </ul>
+    </ul>
+  </div>
+</div>
+```
+
+## Contributing
+
+Contribution to the gem is very much welcome!
+
+1. Fork it (https://github.com/coffeebrewapps/coffeebrew_jekyll_archives/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_archives/`).
+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_archives
+│   ├── config.yml
+│   ├── generator.rb
+│   ├── page.rb
+│   ├── validator.rb
+│   └── version.rb
+└── coffeebrew_jekyll_archives.rb
+```
+
+The files that are currently in the repo:
+
+| File | Description |
+| --- | --- |
+| `lib/coffeebrew_jekyll_archives/config.yml` | This contains the default configuration for the plugin to generate the archive indexes. |
+| `lib/coffeebrew_jekyll_archives/generator.rb` | This is the generator that reads the configuration and generate the index pages. |
+| `lib/coffeebrew_jekyll_archives/page.rb` | This is the abstract model of the index pages. |
+| `lib/coffeebrew_jekyll_archives/validator.rb` | This validates the configuration. |
+| `lib/coffeebrew_jekyll_archives/version.rb` | This contains the version number of the gem. |
+| `lib/coffeebrew_jekyll_archives.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_archives_spec.rb
+├── dest
+├── fixtures
+│   ├── _config.yml
+│   ├── _data
+│   │   └── navigation.yml
+│   ├── _includes
+│   │   └── navigation.html
+│   ├── _layouts
+│   │   ├── archive.html
+│   │   └── default.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
+├── scenarios
+│   ├── default
+│   │   ├── _site
+│   │   │   ├── archives
+│   │   │   │   ├── 2021
+│   │   │   │   │   ├── 03
+│   │   │   │   │   │   ├── 12
+│   │   │   │   │   │   │   └── index.html
+│   │   │   │   │   │   ├── 28
+│   │   │   │   │   │   │   └── index.html
+│   │   │   │   │   │   └── index.html
+│   │   │   │   │   ├── 05
+│   │   │   │   │   │   ├── 03
+│   │   │   │   │   │   │   └── index.html
+│   │   │   │   │   │   └── index.html
+│   │   │   │   │   └── index.html
+│   │   │   │   └── 2023
+│   │   │   │       ├── 02
+│   │   │   │       │   ├── 21
+│   │   │   │       │   │   └── index.html
+│   │   │   │       │   └── index.html
+│   │   │   │       └── index.html
+│   │   │   └── archives.html
+│   │   └── context.rb
+│   └── invalid_config_keys
+│       └── context.rb
+└── spec_helper.rb
+```
+
+The files that are currently in the repo:
+
+| File | Description |
+| --- | --- |
+| `spec/coffeebrew_jekyll_archives_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 archive index pages. |
+| `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 archive index 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:archives:test:create_success[test_scenario]
+```
+
+This will generate a placeholder file and directory:
+
+```bash
+spec
+├── coffeebrew_jekyll_archives_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:archives:test:create_failure[test_scenario]
+```
+
+This will generate a placeholder file and directory:
+
+```bash
+spec
+├── coffeebrew_jekyll_archives_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_archives/config.yml

@@ -0,0 +1,30 @@
+---
+archives:
+  navigation:
+    data: "navigation"
+    name: "Archives"
+    before:
+    after:
+  depths: 3
+  title_format:
+    root:
+      type: "string"
+      style: "/"
+    year:
+      type: "date"
+      style: "%Y"
+    month:
+      type: "date"
+      style: "%b, %Y"
+    day:
+      type: "date"
+      style: "%d %b, %Y"
+  root_dir: "/"
+  root_basename: "archives"
+  index_root: "/archives"
+  index_basename: "index"
+  permalink:
+    root: "/:root_dir"
+    year: "/:root_dir/:index_root/:year"
+    month: "/:root_dir/:index_root/:year/:month"
+    day: "/:root_dir/:index_root/:year/:month/:day"

data/lib/coffeebrew_jekyll_archives/generator.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "./page"
+require_relative "./validator"
+
+module Coffeebrew
+  module Jekyll
+    module Archives
+      class Generator < ::Jekyll::Generator
+        safe true
+        priority :lowest
+
+        def generate(site)
+          @site = site
+
+          validate!
+
+          @site.pages << root_page
+          @site.data["archives"] = root_page
+
+          return unless navigation_config
+
+          generate_navigation
+        end
+
+        private
+
+        def config
+          @config ||= ::Jekyll::Utils.deep_merge_hashes(default_config["archives"], @site.config["archives"].to_h)
+        end
+
+        def validate!
+          validator = Coffeebrew::Jekyll::Archives::Validator.new(config)
+          validator.validate!
+        end
+
+        def root_page
+          @root_page ||= Coffeebrew::Jekyll::Archives::Page.new(
+            :root, @site, config, nil, @site.posts.docs, config["depths"],
+            year: 1, month: 1, day: 1
+          )
+        end
+
+        def navigation_config
+          @navigation_config ||= config["navigation"]
+        end
+
+        def navigation_data
+          @navigation_data ||= @site.data[navigation_config["data"]]
+        end
+
+        def default_config_path
+          @default_config_path ||= File.expand_path("config.yml", __dir__)
+        end
+
+        def default_config
+          @default_config ||= YAML.safe_load(File.read(default_config_path))
+        end
+
+        def menu_data
+          @menu_data ||= {
+            "name" => navigation_config["name"],
+            "link" => root_page.url
+          }
+        end
+
+        def find_menu_index(menu_name)
+          navigation_data.index do |menu|
+            menu["name"] == menu_name
+          end
+        end
+
+        def insert_position
+          @insert_position ||= if navigation_config["before"]
+                                 [navigation_config["before"], 0]
+                               elsif navigation_config["after"]
+                                 [navigation_config["after"], 1]
+                               else
+                                 []
+                               end
+        end
+
+        def generate_navigation
+          if insert_position.empty?
+            navigation_data << menu_data
+          else
+            menu_name, offset = insert_position
+            found_index = find_menu_index(menu_name)
+            navigation_data.insert(found_index + offset, menu_data)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coffeebrew_jekyll_archives/page.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Coffeebrew
+  module Jekyll
+    module Archives
+      class Page < ::Jekyll::Page # rubocop:disable Metrics/ClassLength
+        HIERARCHY = {
+          "root" => "year",
+          "year" => "month",
+          "month" => "day"
+        }.freeze
+
+        DEPTHS = {
+          "root" => 0,
+          "year" => 1,
+          "month" => 2,
+          "day" => 3
+        }.freeze
+
+        attr_reader :type, :date, :parent, :collection
+
+        def initialize(type, site, config, parent, collection, depths, year:, month:, day:) # rubocop:disable Lint/MissingSuper, Metrics/ParameterLists
+          @type = type
+          @site = site
+          @config = config
+          @base = site.source
+          @date = Date.new(year.to_i, month.to_i, day.to_i)
+          @ext = ".html"
+          @parent = parent
+          @collection = collection
+          @depths = depths
+          build_data
+        end
+
+        def sub_pages
+          @sub_pages ||= if current_depth < @depths
+                           child_type = HIERARCHY[type.to_s].to_sym
+                           group_collection_by(collection, child_type).each_with_object([]) do |(attr, items), pages|
+                             fields = date_fields.merge(child_type => attr)
+                             child_page = Page.new(child_type, @site, @config, self, items, @depths, **fields)
+                             add_child_page(pages, child_page)
+                           end
+                         else
+                           []
+                         end
+        end
+
+        def url_placeholders
+          {
+            path: dir,
+            basename: basename,
+            output_ext: output_ext
+          }
+        end
+
+        def ancestors
+          @ancestors ||= begin
+            arr = []
+            current_parent = parent
+            while current_parent
+              arr.unshift(current_parent)
+              current_parent = current_parent.parent
+            end
+            arr
+          end
+        end
+
+        def dir
+          @dir ||= begin
+            format = @config.dig("permalink", type.to_s)
+            ::Jekyll::URL.new(
+              template: format,
+              placeholders: dir_placeholders,
+              permalink: nil
+            ).to_s
+          end
+        end
+
+        def year
+          @year ||= date.strftime("%Y")
+        end
+
+        def month
+          @month ||= date.strftime("%m")
+        end
+
+        def day
+          @day ||= date.strftime("%d")
+        end
+
+        def title
+          @title ||= case title_format_type
+                     when :date
+                       date.strftime(title_format_style)
+                     when :string
+                       format(title_format_style, year: year, month: month, day: day)
+                     end
+        end
+
+        def basename
+          @basename ||= case type.to_sym
+                        when :root
+                          @config["root_basename"]
+                        else
+                          @config["index_basename"]
+                        end
+        end
+
+        def name
+          @name ||= "#{basename}#{ext}"
+        end
+
+        private
+
+        def date_fields
+          @date_fields ||= { year: year, month: month, day: day }
+        end
+
+        def add_child_page(pages, child_page)
+          pages << child_page
+          @site.pages << child_page
+        end
+
+        def dir_placeholders
+          @dir_placeholders ||= {
+            root_dir: @config["root_dir"],
+            index_root: @config["index_root"],
+            year: year,
+            month: month,
+            day: day
+          }
+        end
+
+        def current_depth
+          @current_depth ||= DEPTHS[type.to_s]
+        end
+
+        def title_format
+          @title_format ||= @config.dig("title_format", type.to_s)
+        end
+
+        def title_format_type
+          @title_format_type ||= title_format["type"].to_sym
+        end
+
+        def title_format_style
+          @title_format_style ||= title_format["style"]
+        end
+
+        def root_index_path
+          @root_index_path ||= "#{@config['root_dir']}#{@config['root_basename']}.html"
+        end
+
+        def build_data # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+          @data = {
+            "dir" => dir,
+            "sub_pages" => sub_pages,
+            "root" => root_index_path,
+            "ancestors" => ancestors,
+            "parent" => parent,
+            "collection" => collection,
+            "title" => title,
+            "year" => year,
+            "month" => month,
+            "day" => day
+          }
+
+          data.default_proc = proc do |_, key|
+            site.frontmatter_defaults.find(relative_path, :archives, key)
+          end
+        end
+
+        def group_collection_by(collection, attr)
+          collection.group_by do |item|
+            item.date.send(attr)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coffeebrew_jekyll_archives/validator.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Coffeebrew
+  module Jekyll
+    module Archives
+      class Validator
+        ALLOWED_CONFIG_KEYS = {
+          "navigation" => {
+            "data" => [],
+            "name" => [],
+            "before" => [],
+            "after" => []
+          },
+          "depths" => [1, 2, 3],
+          "title_format" => {
+            "root" => {
+              "type" => %w[string date],
+              "style" => []
+            },
+            "year" => {
+              "type" => %w[string date],
+              "style" => []
+            },
+            "month" => {
+              "type" => %w[string date],
+              "style" => []
+            },
+            "day" => {
+              "type" => %w[string date],
+              "style" => []
+            }
+          },
+          "root_dir" => [],
+          "root_basename" => [],
+          "index_root" => [],
+          "index_basename" => [],
+          "permalink" => {
+            "root" => [],
+            "year" => [],
+            "month" => [],
+            "day" => []
+          }
+        }.freeze
+
+        def initialize(config)
+          @config = config
+          @errors = []
+        end
+
+        def validate!
+          parse(@config, ALLOWED_CONFIG_KEYS, ["archives"])
+
+          return if @errors.empty?
+
+          ::Jekyll.logger.error "'archives' config is set incorrectly."
+          ::Jekyll.logger.error "Errors:", @errors
+
+          raise ::Jekyll::Errors::InvalidConfigurationError, "'archives' config is set incorrectly."
+        end
+
+        private
+
+        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)
+        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_archives/version.rb

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

data/lib/coffeebrew_jekyll_archives.rb

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

metadata

@@ -0,0 +1,175 @@
+--- !ruby/object:Gem::Specification
+name: coffeebrew_jekyll_archives
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Coffee Brew Apps
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-04-06 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'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.6
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.12.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.12.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.19.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.19.0
+description: A Jekyll plugin to generate blog post archives
+email:
+- coffeebrewapps@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
+- LICENSE
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/coffeebrew_jekyll_archives.rb
+- lib/coffeebrew_jekyll_archives/config.yml
+- lib/coffeebrew_jekyll_archives/generator.rb
+- lib/coffeebrew_jekyll_archives/page.rb
+- lib/coffeebrew_jekyll_archives/validator.rb
+- lib/coffeebrew_jekyll_archives/version.rb
+homepage: https://coffeebrewapps.com/coffeebrew_jekyll_archives
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib/coffeebrew_jekyll_archives
+- 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.6
+signing_key:
+specification_version: 4
+summary: A Jekyll plugin to generate blog post archives
+test_files: []