jekyll-collection-pages 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97a284bb86cc0d06f068f04d67815db35d54294af4449a7070b29d4d5ddca255
-  data.tar.gz: 35b687df7a07642a508ed417e26d1b32ba4c9627366370a9de711e786ba99b07
+  metadata.gz: 9fd1f1722ec16a60ac61dd1779dad45c8107720762e03c2e9ae623784d3696ce
+  data.tar.gz: 7ce8708d2ec0759f9ec478ec89691f102b6204da925cb25ff7374390f4aeee88
 SHA512:
-  metadata.gz: 8481bd3ea5c40e2dec1f7a5b007a6735e9162e874f4a5ee3407454163036f6427e6d1f2f6137ede947c4b8cb8438b3365b64358baa05c90f36a5b0df60d953de
-  data.tar.gz: a23a1f8ec7644c2151fdd36a159c2fe5b5adac1d673ccab2e79cf2b47968e96d7cc8a0ab0e82e6ea026556c00e2c82394fc8e8d4beeb1a827ca974f11f5f028f
+  metadata.gz: 9fed8faba1a44eb009b4a83d6c0844a1ef321faf1cdbd115a7997124080cfc112157147b4c0a07405372a048327084032f4abfef6b93865fd855a5f6bca4da0d
+  data.tar.gz: 45b2ef4c09b213f5c376472adb1acf1ad9be7811b1d5686cd3b78ef69b417400e2984c0c70809536d7ed572442e32d4e99460ec673c22966515d3c68a730d9d8

data/.devcontainer/devcontainer.json

@@ -5,7 +5,7 @@
 	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
 	"image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
 	"features": {
-		"ghcr.io/devcontainers/features/ruby:1": {
+		"ghcr.io/devcontainers/features/ruby:2": {
 			"version": "3.3.4"
 		}
 	},
@@ -19,9 +19,17 @@
 		35729
 	],
 	// Use 'postCreateCommand' to run commands after the container is created.
-	"postCreateCommand": ".devcontainer/post-create.sh"
+	"postCreateCommand": ".devcontainer/post-create.sh",
 	// Configure tool-specific properties.
-	// "customizations": {},
+	"customizations": {
+		"vscode": {
+			"settings": {
+				"rubyLsp.rubyVersionManager": {
+					"identifier": "none"
+				}
+			}
+		}
+	}
 	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
 	// "remoteUser": "root"
 }

data/.github/workflows/release_draft.yml

@@ -51,7 +51,7 @@ jobs:
         run: bundle install
 
       - name: Create Draft Pull Request
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
         with:
           commit-message: "Bump version to ${{ needs.draft-release.outputs.tag_name }}"
           branch: release/draft

data/.gitignore

@@ -19,3 +19,4 @@ _site/
 **/.jekyll-cache/
 Gemfile.lock
 .env
+/.ruby-lsp/

data/.rubocop.yml

@@ -20,14 +20,14 @@ Layout/LineLength:
 # Metrics cops
 # ----------------------------------------
 Metrics/AbcSize:
-  Max: 23
+  Max: 24
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
 Metrics/ClassLength:
   Max: 240
 Metrics/CyclomaticComplexity:
-  Max: 11
+  Max: 12
 Metrics/MethodLength:
   Max: 20
 Metrics/ModuleLength:

data/.vscode/settings.json

@@ -1,5 +1,2 @@
 {
-    "rubyLsp.rubyVersionManager": {
-        "identifier": "none"
-    },
 }

data/Gemfile

@@ -9,11 +9,13 @@ gem 'webrick', '~> 1.8'
 
 group :jekyll_plugins do
   gem 'jekyll-feed'
+  gem 'jekyll-octicons'
   gem 'jekyll-paginate'
   gem 'jekyll-redirect-from'
   gem 'jekyll-relative-links'
   gem 'jekyll-sitemap'
-  gem 'jekyll-theme-profile' # needed for themeing
+  gem 'jekyll-theme-primerpages' # needed for themeing
+  gem 'jekyll-toc'
 end
 
 group :development do

data/README.md

@@ -42,6 +42,7 @@ collection_pages:
 ```
 
 Key options:
+
 - `collection`: collection label (matches `collections` config).
 - `field`: front-matter key to group documents (string or list values).
 - `path`: base folder for generated pages (relative to site root).
@@ -72,7 +73,6 @@ Run `bundle exec jekyll serve` and visit the generated paths, e.g. `/docs/catego
 - `page.posts`: documents in that field bucket.
 - `page.paginator`: pagination data when `paginate` is set (same shape as Jekyll paginator).
 
-
 ```html
 {% raw %}
 ---
@@ -91,8 +91,8 @@ layout: default
 
 Every build populates a hash at `site.data.collection_pages[collection][field]` that contains:
 
-- `template` → the full sanitized template used for creating pages with placeholders intact.  Directory-style values from `_config.yml` are auto-appended with `:field/page:num/index.html`. (e.g. `/docs/category/:field/page:num/index.html`)
-- `permalink` → the sanitized template for the index with placeholders intact (e.g. `/docs/category/:field/`)
+- `template` → the sanitized template the generator used (`/docs/category/:field/index.html` for unpaginated configs, `/docs/category/:field/page:num/index.html` when `paginate` is positive).
+- `permalink` → the sanitized template for the index with placeholders intact (`:num` never appears here because it always points to page 1, e.g. `/docs/category/:field/`)
 - `pages` → documents grouped by label (`{ label => [documents...] }`)
 - `labels`: metadata describing the generated index pages
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/demo/_config.yml

@@ -1,4 +1,4 @@
-theme: jekyll-theme-profile
+theme: jekyll-theme-primerpages
 style: topbar
 title: Jekyll Collection Pages plugin
 repository: PrimerPages/jekyll-collection-pages
@@ -75,7 +75,6 @@ relative_links:
 plugins:
   - jekyll-paginate
   - jekyll-collection-pages
-  - jekyll-github-metadata
   - jekyll-octicons
   - jekyll-relative-links
   - jekyll-seo-tag

data/demo/_docs/configuration-guide.md

@@ -44,7 +44,7 @@ collection_pages:
 
 If you only need a single entry, `collection_pages` can also be a hash (the plugin normalises it internally). The array form keeps things consistent once you add more targets.
 
-Each `path` above is treated as a template—directory values automatically expand to `docs/<section>/categories/:field/page:num/index.html`. To switch to file-style permalinks, include the placeholders yourself, e.g. `docs/getting-started/categories/:field-page:num.html`.
+Each `path` above is treated as a template—directory and can take `:field` and `:num` as placeholders.  It is recommended to set only set the directory since values automatically expand to `<path>/:field/page:num/index.html`.  The first page, and when pagination is off the generator will create pages in `<path>/:field/index.html`.
 
 ## Configuration options
 
@@ -66,13 +66,15 @@ Make sure every document you expect to index sets this field. When the field hol
 
 - Type: `String`  
 - Required: ✔  
-- Description: Path template relative to the site source. It must contain exactly one `:field` placeholder (replaced with the slugified field value) and one `:num` placeholder (replaced with the page number). When you omit placeholders in a directory-style path, the plugin automatically appends them as `<path>/:field/page:num/index.html`. When you provide a filename (ends in `.html`/`.htm`), you must include both placeholders yourself. Leading/trailing slashes are stripped either way.
+- Description: Path template relative to the site source. It can also include a `:field` and a `:num` placeholder which are appended to the path if they are ommitted `:field/page:num/index.html` (recommended).
+    - `:field`: This placeholder is for the value of the field for the page.
+    - `:num`: This placeholder is for the page number of the pagination.
 
 Rules enforced by the generator:
 
-- `:field` must appear before `:num`, and they cannot be in the same path segment.
-- Paths ending in `.html`/`.htm` must include both placeholders already.
-- Leaving `path` blank defaults to `<collection>/:field/page:num/index.html`.
+- When `:num` is present it must appear after `:field`, and the two placeholders cannot live in the same segment.
+- Paths ending in `.html`/`.htm` must include the required placeholders explicitly.
+- Leaving `path` blank defaults to `<collection>/:field/index.html` (or `<collection>/:field/page:num/index.html` when paginated).
 
 ### `layout`
 
@@ -94,8 +96,8 @@ Set `paginate` to `nil`, omit the key, or use a non-positive number to render a
 
 At build time the plugin exports `site.data.collection_pages[collection_name][field]`, which contains:
 
-- `template` → the full sanitized template used for creating pages with placeholders intact.  Directory-style values from `_config.yml` are auto-appended with `:field/page:num/index.html`. (e.g. `/docs/category/:field/page:num/index.html`)
-- `permalink` → the sanitized template for the index with placeholders intact (e.g. `/docs/category/:field/`)
+- `template` → the sanitized template used to create each index. Directory values inherit `<path>/:field/index.html` and add `/page:num/` only when pagination is enabled (e.g. `/docs/category/:field/index.html` or `/docs/category/:field/page:num/index.html`).
+- `permalink` → the sanitized template for the index with placeholders intact (no `:num`, since it always points to page one, e.g. `/docs/category/:field/`)
 - `pages` → documents grouped by label (`{ label => [documents...] }`)
 - `labels`: metadata describing the generated index pages
 

data/demo/_docs/examples.md

@@ -16,14 +16,9 @@ collection_pages:
     path: blog/category
     layout: category_page.html
     paginate: 10
-  - collection: posts
-    field: category
-    path: blog/category/:field-page:num.html
-    layout: category_page.html
-    paginate: 10
 ```
 
-The first entry produces folder-style pagination such as `/blog/category/reference/` and `/blog/category/reference/page2/`. The second entry demonstrates file-style pagination (e.g. `/blog/category/reference.html`, `/blog/category/reference-page2.html`). Both obey the same placeholder rules; pick the style that fits your permalink scheme.
+This configuration uses folder-style pagination such as `/blog/category/reference/` and `/blog/category/reference/page2/`. Stick with this pattern for the most compatible URLs.
 
 Render a category listing with the exported data registry:
 

data/demo/_docs/generated-data.md

@@ -45,7 +45,7 @@ The structure is intentionally compatible with existing theme includes that expe
 `labels` exposes metadata about each generated index:
 
 - `index`: the first generated index page (`index.html`)
-- `pages`: array of all `TagIndexPage` objects
+- `pages`: array of all generated `TagPage` objects
 
 Example:
 

data/demo/_docs/troubleshooting.md

@@ -41,8 +41,8 @@ Having trouble seeing generated pages or data? Start here.
 
 ## Path template errors
 
-- `path` values must resolve to exactly one `:field` placeholder and one `:num` placeholder. Directory-style paths (no `.html`/`.htm`) automatically become `<path>/:field/page:num/index.html`, but explicit filenames must include both placeholders.
-- `:field` must appear before `:num`, and they cannot live in the same path segment.
+- `path` values must resolve to exactly one `:field` placeholder. Add a single `:num` placeholder only when the configuration sets a positive `paginate` value. Directory-style paths (no `.html`/`.htm`) automatically become `<path>/:field/index.html`, but  Explicit filenames must include the required placeholders.
+- Whenever `:num` is present it must appear after `:field`, and they cannot live in the same path segment.
 - When the build fails with an error referencing these placeholders, trim any trailing slashes and adjust the order. The generator logs the sanitized template in debug mode so you can confirm the final value.
 
 ## Liquid include expects `site.tags`

data/demo/index.md

@@ -28,7 +28,7 @@ See how `jekyll-collection-pages` organizes technical documentation:
 
 See how `jekyll-collection-pages` can organize collections like posts:
 
-- [Tag directory](directory.md)
+- [Generated pages directory](directory.md)
 - [Tag index](tags.md)
 - [Tag gallery](gallery.md)
 
@@ -52,7 +52,7 @@ Ready to use `jekyll-collection-pages` in your own project?
   {%- include post-card.html border="border-top" %}
   {%- endif %}
 {% endfor %}
-</div>>
+</div>
 
 
 

data/lib/jekyll/collection_pages/collection_config.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module CollectionPages
+    class CollectionConfig
+      attr_reader :collection_name, :tag_field, :tag_base_path, :tag_layout, :per_page
+
+      def initialize(config)
+        unless config.is_a?(Hash)
+          Jekyll.logger.error('CollectionPages:', "Invalid collection config entry: #{config.inspect}.")
+          raise ArgumentError, "Invalid collection_pages config entry. #{config.inspect}."
+        end
+        @collection_name = config['collection']
+        @tag_field = config['field']
+        @tag_base_path = config['path'] || @collection_name
+        @tag_layout = normalize_layout(config['layout'] || 'collection_layout')
+        @per_page = normalize_paginate_value(config['paginate'])
+
+        validate_config
+      end
+
+      private
+
+      def validate_config
+        missing_keys = []
+        missing_keys << 'collection' unless @collection_name
+        missing_keys << 'field' unless @tag_field
+        return if missing_keys.empty?
+
+        Jekyll.logger.error('CollectionPages:', "Missing required config keys: #{missing_keys.join(', ')}.")
+        raise ArgumentError, "Invalid collection_pages config entry. Missing: #{missing_keys.join(', ')}."
+      end
+
+      def normalize_paginate_value(value)
+        return nil if value.nil?
+
+        per_page = Integer(value)
+        return per_page if per_page.positive?
+
+        Jekyll.logger.warn('CollectionPages:',
+                           "Non-positive paginate value #{value.inspect} for collection '#{@collection_name}' field '#{@tag_field}'. " \
+                           'Falling back to single page generation.')
+        nil
+      rescue ArgumentError, TypeError
+        raise ArgumentError,
+              "Invalid paginate value #{value.inspect} for collection '#{@collection_name}' field '#{@tag_field}'. Expected a numeric value."
+      end
+
+      def normalize_layout(layout)
+        layout.to_s.sub(/\.[^.]+\z/, '').sub(%r{\A_layouts/}, '')
+      end
+    end
+  end
+end

data/lib/jekyll/collection_pages/collection_pager.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module CollectionPages
+    class CollectionPager
+      def initialize(site, config)
+        @site = site
+        @config = config
+        @tags_with_docs = sorted_tags(site, config.collection_name, config.tag_field)
+        path_template = PathTemplate.new(raw_template: config.tag_base_path, tag_field: config.tag_field, collection_name: config.collection_name,
+                                         require_num: !config.per_page.nil? && config.per_page.positive?)
+        @template = path_template.template
+        @permalink = TagPath.new(@template, ':field', slugify_value: false).url_for(1)
+      end
+
+      def create_pages
+        documents_map = {}
+        metadata_map = {}
+        @tags_with_docs.each do |tag, posts_with_tag|
+          page_count = TagPager.calculate_pages(posts_with_tag, @config.per_page)
+          tag_pages = []
+          (1..page_count).each do |page_num|
+            tag_page = build_page(@site, tag, posts_with_tag, page_num)
+            @site.pages << tag_page
+            tag_pages << tag_page
+          end
+          documents_map[tag] = posts_with_tag
+          metadata_map[tag] = {
+            'pages' => tag_pages,
+            'index' => tag_pages.first
+          }
+          Jekyll.logger.info('CollectionPages:',
+                             "Generated #{tag_pages.size} page(s) for tag '#{tag}' in collection '#{@config.collection_name}'.")
+        end
+
+        set_metadata(documents_map, metadata_map)
+      end
+
+      private
+
+      def set_metadata(documents_map, metadata_map)
+        @site.data['collection_pages'] ||= {}
+        collection_registry = @site.data['collection_pages'][@config.collection_name] ||= {}
+        collection_registry[@config.tag_field] = {
+          'template' => @template,
+          'permalink' => @permalink,
+          'labels' => metadata_map,
+          'pages' => documents_map
+        }
+      end
+
+      def build_page(site, tag, posts_with_tag, page_num)
+        tag_path = TagPath.new(@template, tag)
+        paginator = TagPager.new(page_num, @config.per_page, posts_with_tag)
+
+        paginator_liquid = paginator.to_liquid.merge(
+          'previous_page_path' => tag_path.url_for(paginator.previous_page),
+          'next_page_path' => tag_path.url_for(paginator.next_page)
+        )
+        TagPage.new(
+          site,
+          {
+            dir: tag_path.dir_for(page_num),
+            name: tag_path.filename_for(page_num),
+            title: tag,
+            tag: tag_path.tag,
+            layout: @config.tag_layout,
+            posts: paginator.posts,
+            page_num: page_num,
+            paginator: @config.per_page ? paginator_liquid : nil
+          }
+        )
+      end
+
+      def sorted_tags(site, collection_name, tag_field)
+        tags = {}
+        collection = site.collections[collection_name]
+        return [] unless collection
+
+        Jekyll.logger.debug('CollectionPages:', "Found collection '#{collection_name}' with #{collection.docs.size} entries.")
+        collection.docs.each do |doc|
+          doc_tags = doc.data[tag_field]
+          next unless doc_tags
+
+          doc_tags = [doc_tags] if doc_tags.is_a?(String)
+          doc_tags.each do |tag|
+            tags[tag] ||= []
+            tags[tag] << doc
+          end
+        end
+        tags.keys.sort.map { |tag| [tag, tags[tag]] }
+      end
+    end
+  end
+end

data/lib/jekyll/collection_pages/path_template.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module CollectionPages
+    INDEXFILE = 'index.html' unless const_defined?(:INDEXFILE)
+
+    class PathTemplate
+      attr_reader :tag_field, :collection_name
+
+      def initialize(raw_template:, tag_field:, collection_name:, require_num: true)
+        @tag_field = tag_field
+        @collection_name = collection_name
+        @require_num = require_num
+        @template = build_effective_template(raw_template)
+      end
+
+      def template
+        "/#{@template}"
+      end
+
+      private
+
+      def build_effective_template(raw)
+        sanitized = sanitize_path(raw)
+        sanitized = default_placeholder if sanitized.empty?
+        sanitized = add_field_placeholder(sanitized)
+        sanitized = add_num_placeholder(sanitized) if @require_num
+        sanitized = add_index(sanitized)
+        Jekyll.logger.debug('CollectionPages:', "Using path template '#{sanitized}' for collection '#{@collection_name}'.")
+        validate_template(sanitized)
+
+        sanitized
+      end
+
+      def sanitize_path(path)
+        path.to_s.strip.sub(%r{^/+}, '').sub(%r{/+\z}, '')
+      end
+
+      def default_placeholder
+        @collection_name.to_s
+      end
+
+      def add_field_placeholder(path)
+        return path if path.include?(':field')
+
+        raise ArgumentError, "Path template '#{path}' must include a ':field' placeholder." if path.end_with?('.html') || path.end_with?('.htm')
+
+        "#{path}/:field"
+      end
+
+      def add_num_placeholder(path)
+        return path if path.include?(':num')
+
+        raise ArgumentError, "Path template '#{path}' must include a ':num' placeholder." if path.end_with?('.html') || path.end_with?('.htm')
+
+        "#{path}/page:num"
+      end
+
+      def add_index(path)
+        return path if path.end_with?('.html') || path.end_with?('.htm')
+
+        "#{path}/#{INDEXFILE}"
+      end
+
+      def validate_template(path)
+        field_count = path.scan(':field').size
+        num_count = path.scan(':num').size
+
+        error_msg = ''
+        error_msg += "Path template '#{path}' must include exactly one ':field' placeholder. " if field_count != 1
+        error_msg += "Path template '#{path}' must include exactly one ':num' placeholder. " if @require_num && num_count != 1
+
+        if num_count.positive? && field_count.positive?
+          field_idx = path.index(':field')
+          num_idx = path.index(':num')
+          error_msg += "In path template '#{path}', ':field' must come before ':num'. " if num_idx < field_idx
+        end
+
+        segments = path.split('/').reject(&:empty?)
+        segments.each do |segment|
+          if segment.include?(':field') && segment.include?(':num')
+            error_msg += "In path template '#{path}', ':field' and ':num' cannot be in the same file segment. "
+          end
+        end
+
+        raise ArgumentError, error_msg unless error_msg.empty?
+      end
+    end
+  end
+end

data/lib/jekyll/collection_pages/tag_page.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module CollectionPages
+    class TagPage < PageWithoutAFile
+      def initialize(site, attributes)
+        dir = attributes[:dir]
+        name = attributes[:name]
+        tag = attributes[:tag]
+        title = attributes[:title]
+        layout = attributes[:layout]
+        posts = attributes[:posts]
+        page_num = attributes[:page_num]
+        paginator = attributes[:paginator]
+
+        # This sets up a page that has no source file on disk.
+        super(site, site.source, dir, name) # also calls process(name) internally
+
+        self.content = '' # virtual page body (optional)
+
+        self.data = {
+          'layout' => layout, # layout NAME (relative path, no _layouts prefix)
+          'tag' => tag.to_s,
+          'title' => title.to_s,
+          'posts' => posts,
+          'page_num' => page_num
+        }
+        data['paginator'] = paginator if paginator
+      end
+    end
+  end
+end

data/lib/jekyll/collection_pages/tag_pager.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module CollectionPages
+    class TagPager
+      attr_reader :page, :per_page, :posts, :total_posts, :total_pages,
+                  :previous_page, :next_page
+
+      LIQUID_MAP = {
+        'page' => :page, # the current page number
+        'per_page' => :per_page, # the number of posts per page
+        'posts' => :posts, # the paginated posts for this page
+        'total_posts' => :total_posts, # the total number of posts being paginated
+        'total_pages' => :total_pages, # the total number of pages
+        'previous_page' => :previous_page, # the previous page number, or nil
+        'next_page' => :next_page # the next page number, or nil
+      }.freeze
+
+      def self.calculate_pages(all_posts, per_page)
+        per_page_value = per_page.to_i
+        return 1 if per_page_value <= 0
+
+        (all_posts.size.to_f / per_page_value).ceil
+      end
+
+      def initialize(page_num, per_page, all_posts)
+        @page = page_num
+        @per_page = per_page.to_i.positive? ? per_page.to_i : 0
+        @total_posts = all_posts.size
+        @total_pages = self.class.calculate_pages(all_posts, @per_page)
+        @posts = slice_posts(all_posts)
+        @previous_page = previous_page_number
+        @next_page = next_page_number(total_pages)
+      end
+
+      def to_liquid
+        LIQUID_MAP.transform_values { |reader| public_send(reader) }
+      end
+
+      private
+
+      def slice_posts(all_posts)
+        return all_posts if @per_page <= 0
+
+        start_index = (@page - 1) * @per_page
+        all_posts.slice(start_index, @per_page) || []
+      end
+
+      def previous_page_number
+        @page > 1 ? @page - 1 : nil
+      end
+
+      def next_page_number(total_pages)
+        @page < total_pages ? @page + 1 : nil
+      end
+    end
+  end
+end

data/lib/jekyll/collection_pages/tag_path.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module CollectionPages
+    class TagPath
+      attr_reader :tag
+
+      def initialize(template, field_value, slugify_value: true)
+        @template = template
+        @tag = slugify_value ? Utils.slugify(field_value.to_s) : field_value.to_s
+        @segments = template.split('/').reject(&:empty?)
+        @explicit_file = file_segment?(@segments.last) && @segments.last.include?(':field')
+      end
+
+      def dir_for(page_number)
+        segments = @segments
+        segments = apply_field_value(segments)
+        segments = page_number == 1 ? remove_paginated_segments(segments) : apply_page_number(segments, page_number)
+        segments = drop_file_segment(segments)
+
+        File.join(*segments)
+      end
+
+      def filename_for(page_number)
+        segments = @segments.last(1)
+        segments = apply_field_value(segments)
+
+        if page_number == 1
+          return segments.join if @explicit_file
+
+          return INDEXFILE
+        end
+
+        segments = apply_page_number(segments, page_number)
+        segments.join
+      end
+
+      def url_for(page_number)
+        return nil if page_number.nil?
+
+        dir = dir_for(page_number)
+        filename = filename_for(page_number)
+        return formatted_index_path(dir) if filename == INDEXFILE
+
+        dir.empty? ? "/#{filename}" : "/#{dir}/#{filename}"
+      end
+
+      private
+
+      def apply_field_value(segments)
+        segments.map do |segment|
+          segment.include?(':field') ? segment.gsub(':field', @tag) : segment
+        end
+      end
+
+      def apply_page_number(segments, page_number)
+        segments.map do |segment|
+          segment.include?(':num') ? segment.gsub(':num', page_number.to_s) : segment
+        end
+      end
+
+      def drop_file_segment(segments)
+        if file_segment?(segments.last)
+          segments[0...-1]
+        else
+          segments
+        end
+      end
+
+      def file_segment?(segment)
+        segment && (segment.end_with?('.html') || segment.end_with?('.htm'))
+      end
+
+      def remove_paginated_segments(segments)
+        number_index = segments.index { |segment| segment.include?(':num') }
+        number_index ? segments[0...number_index] : segments
+      end
+
+      def formatted_index_path(dir)
+        return '/' if dir.empty?
+
+        "/#{dir}/"
+      end
+    end
+  end
+end

data/lib/jekyll/collection_pages/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module CollectionPages
+    VERSION = File.read(File.expand_path('../../../VERSION', __dir__)).strip
+  end
+end

data/lib/jekyll/collection_pages.rb

@@ -1,165 +1,16 @@
 # frozen_string_literal: true
 
+require_relative 'collection_pages/collection_config'
+require_relative 'collection_pages/collection_pager'
+require_relative 'collection_pages/path_template'
+require_relative 'collection_pages/tag_page'
+require_relative 'collection_pages/tag_pager'
+require_relative 'collection_pages/tag_path'
+require_relative 'collection_pages/version'
+
 module Jekyll
   module CollectionPages
-    INDEXFILE = 'index.html'
-
-    class PathTemplate
-      def initialize(raw_template:, tag_field:, collection_name:)
-        @tag_field = tag_field
-        @collection_name = collection_name
-        @template = build_effective_template(raw_template)
-      end
-
-      def for_tag(tag_value)
-        TagPathResolver.new(@template, tag_value)
-      end
-
-      def permalink
-        TagPathResolver.new(@template, ':field', slugify_value: false).url_for(1)
-      end
-
-      def template
-        "/#{@template}"
-      end
-
-      private
-
-      def build_effective_template(raw)
-        sanitized = sanitize_path(raw)
-        sanitized = default_placeholder if sanitized.empty?
-        sanitized = add_field_placeholder(sanitized)
-        sanitized = add_num_placeholder(sanitized)
-        sanitized = add_index(sanitized)
-        Jekyll.logger.debug('CollectionPages:', "Using path template '#{sanitized}' for collection '#{@collection_name}'.")
-        validate_template(sanitized)
-
-        sanitized
-      end
-
-      def sanitize_path(path)
-        path.to_s.strip.sub(%r{^/+}, '').sub(%r{/+\z}, '')
-      end
-
-      def default_placeholder
-        @collection_name.to_s
-      end
-
-      def add_field_placeholder(path)
-        return path if path.include?(':field')
-
-        raise ArgumentError, "Path template '#{path}' must include a ':field' placeholder." if path.end_with?('.html') || path.end_with?('.htm')
-
-        "#{path}/:field"
-      end
-
-      def add_num_placeholder(path)
-        return path if path.include?(':num')
-
-        raise ArgumentError, "Path template '#{path}' must include a ':num' placeholder." if path.end_with?('.html') || path.end_with?('.htm')
-
-        "#{path}/page:num"
-      end
-
-      def add_index(path)
-        return path if path.end_with?('.html') || path.end_with?('.htm')
-
-        "#{path}/#{CollectionPages::INDEXFILE}"
-      end
-
-      def validate_template(path)
-        field_count = path.scan(':field').size
-        num_count = path.scan(':num').size
-
-        error_msg = ''
-        error_msg += "Path template '#{path}' must include exactly one ':field' placeholder. " if field_count != 1
-        error_msg += "Path template '#{path}' must include exactly one ':num' placeholder. " if num_count != 1
-
-        if num_count.positive? && field_count.positive?
-          field_idx = path.index(':field')
-          num_idx = path.index(':num')
-          error_msg += "In path template '#{path}', ':field' must come before ':num'. " if num_idx < field_idx
-        end
-
-        segments = path.split('/').reject(&:empty?)
-        segments.each do |segment|
-          if segment.include?(':field') && segment.include?(':num')
-            error_msg += "In path template '#{path}', ':field' and ':num' cannot be in the same file segment. "
-          end
-        end
-
-        raise ArgumentError, error_msg unless error_msg.empty?
-      end
-
-      class TagPathResolver
-        def initialize(template, field_value, slugify_value: true)
-          @template = template
-          @value = slugify_value ? Utils.slugify(field_value.to_s) : field_value.to_s
-          @segments = template.split('/').reject(&:empty?)
-        end
-
-        def dir_for(page_number)
-          segments = @segments
-          segments = apply_field_value(segments)
-          segments = page_number == 1 ? remove_paginated_segments(segments) : apply_page_number(segments, page_number)
-          segments = drop_file_segment(segments)
-
-          File.join(*segments)
-        end
-
-        def filename_for(page_number)
-          return CollectionPages::INDEXFILE if page_number == 1
-
-          segments = @segments.last(1)
-          segments = apply_field_value(segments)
-          segments = apply_page_number(segments, page_number)
-          segments.join
-        end
-
-        def url_for(page_number)
-          dir = dir_for(page_number)
-          filename = filename_for(page_number)
-          return formatted_index_path(dir) if filename == CollectionPages::INDEXFILE
-
-          dir.empty? ? "/#{filename}" : "/#{dir}/#{filename}"
-        end
-
-        private
-
-        def apply_field_value(segments)
-          segments.map do |segment|
-            segment.include?(':field') ? segment.gsub(':field', @value) : segment
-          end
-        end
-
-        def apply_page_number(segments, page_number)
-          segments.map do |segment|
-            segment.include?(':num') ? segment.gsub(':num', page_number.to_s) : segment
-          end
-        end
-
-        def drop_file_segment(segments)
-          if segments.last.end_with?('.html') || segments.last.end_with?('.htm')
-            segments[0...-1]
-          else
-            segments
-          end
-        end
-
-        def remove_paginated_segments(segments)
-          number_index = segments.index { |segment| segment.include?(':num') }
-          number_index ? segments[0...number_index] : segments
-        end
-
-        def formatted_index_path(dir)
-          return '/' if dir.empty?
-
-          "/#{dir}/"
-        end
-      end
-    end
-
-    class TagPagination < Generator
+    class CollectionPages < Generator
       safe true
       priority :lowest
 
@@ -176,208 +27,19 @@ module Jekyll
           config.each do |collection_config|
             generate_for_config(site, collection_config)
           end
+        else
+          Jekyll.logger.error('CollectionPages:', 'Invalid configuration.')
         end
         Jekyll.logger.debug('CollectionPages:', "Generation complete. Total pages: #{site.pages.size}")
       end
 
       def generate_for_config(site, config)
-        collection_name = config['collection']
-        tag_field = config['field']
-        tag_base_path = config['path']
-        tag_layout = config['layout'] || 'collection_layout.html'
-        per_page = normalize_paginate_value(config['paginate'], collection_name, tag_field)
-        Jekyll.logger.debug('CollectionPages:', "Generating pages for collection: #{collection_name}::#{tag_field}")
-
-        path_template = PathTemplate.new(raw_template: tag_base_path, tag_field: tag_field, collection_name: collection_name)
-
-        site.data['collection_pages'] ||= {}
-
-        documents_map, metadata_map = generate_paginated_tags(site, path_template, tag_layout, collection_name, tag_field, per_page)
-
-        collection_registry = site.data['collection_pages'][collection_name] ||= {}
-        collection_registry[tag_field] = {
-          'template' => path_template.template,
-          'permalink' => path_template.permalink,
-          'labels' => metadata_map,
-          'pages' => documents_map
-        }
-      end
-
-      def sorted_tags(site, collection_name, tag_field)
-        tags = {}
-        collection = site.collections[collection_name]
-        return [] unless collection
-
-        Jekyll.logger.debug('CollectionPages:', "Found collection '#{collection_name}' with #{collection.docs.size} entries.")
-        collection.docs.each do |doc|
-          doc_tags = doc.data[tag_field]
-          next unless doc_tags
-
-          doc_tags = [doc_tags] if doc_tags.is_a?(String)
-          doc_tags.each do |tag|
-            tags[tag] ||= []
-            tags[tag] << doc
-          end
-        end
-        tags.keys.sort.map { |tag| [tag, tags[tag]] }
-      end
-
-      def generate_paginated_tags(site, path_template, tag_layout, collection_name, tag_field, per_page)
-        tags_with_docs = sorted_tags(site, collection_name, tag_field)
-
-        documents_map = {}
-        metadata_map = {}
-
-        tags_with_docs.each do |tag, posts_with_tag|
-          tag_path = path_template.for_tag(tag)
-
-          page_count = TagPager.calculate_pages(posts_with_tag, per_page)
-          tag_pages = []
-          (1..page_count).each do |page_num|
-            paginator = TagPager.new(page_num, per_page, posts_with_tag, tag_path) if per_page
-            posts_for_page = paginator ? paginator.posts : posts_with_tag
-            page_dir = tag_path.dir_for(page_num)
-            page_filename = tag_path.filename_for(page_num)
-            tag_page = build_page(site, page_dir, page_filename, tag, tag_layout, posts_for_page, page_num, paginator)
-            site.pages << tag_page
-            tag_pages << tag_page
-          end
-
-          documents_map[tag] = posts_with_tag
-          metadata_map[tag] = {
-            'pages' => tag_pages,
-            'index' => tag_pages.first
-          }
-          Jekyll.logger.info('CollectionPages:',
-                             "Generated #{tag_pages.size} page(s) for tag '#{tag}' in collection '#{collection_name}'.")
-        end
-
-        [documents_map, metadata_map]
-      end
-
-      def build_page(site, dir, page_filename, tag, layout, posts, page_num, paginator = nil)
-        TagIndexPage.new(
-          site,
-          {
-            dir: dir,
-            name: page_filename,
-            tag: tag,
-            layout: layout,
-            posts: posts,
-            page_num: page_num,
-            paginator: paginator
-          }
-        )
-      end
-
-      private
-
-      def normalize_paginate_value(value, collection_name, tag_field)
-        return nil if value.nil?
-
-        per_page = Integer(value)
-        return per_page if per_page.positive?
-
-        Jekyll.logger.warn('CollectionPages:',
-                           "Non-positive paginate value #{value.inspect} for collection '#{collection_name}' field '#{tag_field}'. " \
-                           'Falling back to single page generation.')
-        nil
-      rescue ArgumentError, TypeError
-        raise ArgumentError,
-              "Invalid paginate value #{value.inspect} for collection '#{collection_name}' field '#{tag_field}'. Expected a numeric value."
+        collection_config = CollectionConfig.new(config)
+        Jekyll.logger.debug('CollectionPages:',
+                            "Generating pages for collection: #{collection_config.collection_name}::#{collection_config.tag_field}")
+        collection_pager = CollectionPager.new(site, collection_config)
+        collection_pager.create_pages
       end
     end
   end
-
-  class TagIndexPage < PageWithoutAFile
-    def initialize(site, attributes)
-      dir = attributes[:dir]
-      name = attributes[:name]
-      tag = attributes[:tag]
-      layout = attributes[:layout]
-      posts = attributes[:posts]
-      page_num = attributes[:page_num]
-      paginator = attributes[:paginator]
-
-      # This sets up a page that has no source file on disk.
-      super(site, site.source, dir, name) # also calls process(name) internally
-
-      self.content = '' # virtual page body (optional)
-
-      self.data = {
-        'layout' => File.basename(layout, '.*'), # layout NAME (no path)
-        'tag' => tag,
-        'title' => tag.to_s,
-        'posts' => posts,
-        'page_num' => page_num
-      }
-      data['paginator'] = paginator if paginator
-    end
-  end
-
-  class TagPager
-    attr_reader :page, :per_page, :posts, :total_posts, :total_pages,
-                :previous_page, :previous_page_path, :next_page, :next_page_path
-
-    LIQUID_MAP = {
-      'page' => :page, # the current page number
-      'per_page' => :per_page, # the number of posts per page
-      'posts' => :posts, # the paginated posts for this page
-      'total_posts' => :total_posts, # the total number of posts being paginated
-      'total_pages' => :total_pages, # the total number of pages
-      'previous_page' => :previous_page, # the previous page number, or nil
-      'previous_page_path' => :previous_page_path, # the previous page path, or nil
-      'next_page' => :next_page, # the next page number, or nil
-      'next_page_path' => :next_page_path # the next page path, or nil
-    }.freeze
-
-    def self.calculate_pages(all_posts, per_page)
-      per_page_value = per_page.to_i
-      return 1 if per_page_value <= 0
-
-      (all_posts.size.to_f / per_page_value).ceil
-    end
-
-    def initialize(page_num, per_page, all_posts, path_resolver)
-      @page = page_num
-      @per_page = per_page.to_i.positive? ? per_page.to_i : 0
-      @total_posts = all_posts.size
-      @total_pages = self.class.calculate_pages(all_posts, @per_page)
-      @posts = slice_posts(all_posts)
-      @path_resolver = path_resolver
-      @previous_page = previous_page_number
-      @next_page = next_page_number(total_pages)
-      @previous_page_path = page_path(@previous_page)
-      @next_page_path = page_path(@next_page)
-    end
-
-    def to_liquid
-      LIQUID_MAP.transform_values { |reader| public_send(reader) }
-    end
-
-    private
-
-    attr_reader :path_resolver
-
-    def slice_posts(all_posts)
-      return all_posts if @per_page <= 0
-
-      start_index = (@page - 1) * @per_page
-      all_posts.slice(start_index, @per_page) || []
-    end
-
-    def previous_page_number
-      @page > 1 ? @page - 1 : nil
-    end
-
-    def next_page_number(total_pages)
-      @page < total_pages ? @page + 1 : nil
-    end
-
-    def page_path(target_page)
-      return unless target_page && target_page <= total_pages
-
-      path_resolver.url_for(target_page)
-    end
-  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-collection-pages
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - allison@allisonthackston.com
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-18 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -96,6 +96,13 @@ files:
 - jekyll-collection-pages.gemspec
 - lib/jekyll-collection-pages.rb
 - lib/jekyll/collection_pages.rb
+- lib/jekyll/collection_pages/collection_config.rb
+- lib/jekyll/collection_pages/collection_pager.rb
+- lib/jekyll/collection_pages/path_template.rb
+- lib/jekyll/collection_pages/tag_page.rb
+- lib/jekyll/collection_pages/tag_pager.rb
+- lib/jekyll/collection_pages/tag_path.rb
+- lib/jekyll/collection_pages/version.rb
 homepage: https://github.com/PrimerPages/jekyll-collection-pages
 licenses:
 - MIT