jekyll-paginate-v3 0.1.0.alpha → 0.1.0.alpha.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfe3b140435a9e8b5011cc8ff234547046323329bf1fba18dc0cdbc649fb1266
-  data.tar.gz: '039c94ad587c94ce7ebf66a828aa856b0092cf9f28a489da2aedc0e7102c2ed7'
+  metadata.gz: 036fbbfba18f61ae73a069e4330fce833a1cb7549704c9bf396961ddd262569f
+  data.tar.gz: 061d674f1bfd29de53bb79bc5a64feb8076a80af38f59be877f3cc77443173ff
 SHA512:
-  metadata.gz: cf32cbe5e10d028b59b8f9807ae3d52bb63421eb0ffa57d3f104b7bdc953f483da24d1453d5974bfcba186e969674ebf1ee1ae39a8e8993456f1033661a873da
-  data.tar.gz: 2278e72f4b899f3cfaf21e62eb55c776fff719bd1e88c2374206f627a070e4dc35cf6bca7613c189590e8be3c5657c40f0e2ad2fd21b4776f48deb7c6b90aa92
+  metadata.gz: e6561b1d072672dabdbace597b3b7d310a3f357f7d9b05a1f6815d7b29e634029faf7828ca8105edf6cc41fd1cab276e215de8343358c53e42b482e005f64235
+  data.tar.gz: 259bd8d452c747203d316a977de290141b11bc1061a39386e0bac81733f1ace2b08ef0b9c1d8092212e232544bb6f8f758e2e49327b6779f54116e555213a7d4

data/lib/jekyll-paginate-v3/generators/pagination_generator.rb

@@ -39,23 +39,14 @@ class PaginationGenerator < Jekyll::Generator
 
 		# Abstract site mutation so the model can add pages or documents
 		# without knowing where Jekyll stores each item type.
-		add_item_lambda = lambda do |item|
-			if item.is_a?(Jekyll::Document)
-				site.collections[item.collection.label].docs << item
-			else
-				site.pages << item
-			end
-			item
+		add_item_lambda = lambda do |item, collection_index: nil|
+			add_site_item(site, item, collection_index: collection_index)
 		end
 
 		# Mirror add_item_lambda for replacing template pages with generated
 		# paginated siblings.
 		remove_item_lambda = lambda do |item|
-			if item.is_a?(Jekyll::Document)
-				site.collections[item.collection.label].docs.delete_if { |doc| doc == item }
-			else
-				site.pages.delete_if { |page| page == item }
-			end
+			remove_site_item(site, item)
 		end
 
 		model = Pagination::Model.new(
@@ -87,6 +78,60 @@ class PaginationGenerator < Jekyll::Generator
 
 	private
 
+	# Adds one generated page/document to the appropriate site collection.
+	#
+	# `collection_index` is optional and is only used when pagination needs
+	# to replace a source collection document without disturbing the
+	# ordering of surrounding documents.
+	def add_site_item(site, item, collection_index: nil)
+		if item.is_a?(Jekyll::Document)
+			add_collection_document(site, item, collection_index: collection_index)
+		else
+			site.pages << item
+		end
+
+		item
+	end
+
+	# Inserts one generated collection document either at a precise source
+	# position or at the end of the collection when no preserved position
+	# is required.
+	def add_collection_document(site, item, collection_index: nil)
+		collection_docs = site.collections[item.collection.label].docs
+		if collection_index.nil?
+			collection_docs << item
+			return
+		end
+
+		safe_collection_index = [[collection_index.to_i, 0].max, collection_docs.length].min
+		collection_docs.insert(safe_collection_index, item)
+	end
+
+	# Removes one item from the site and returns collection position
+	# metadata when the removed item came from a collection.
+	def remove_site_item(site, item)
+		if item.is_a?(Jekyll::Document)
+			return remove_collection_document(site, item)
+		end
+
+		site.pages.delete_if { |page| page.equal?(item) }
+		nil
+	end
+
+	# Removes one collection document by exact array position so the
+	# generated replacement can later reuse the same slot.
+	def remove_collection_document(site, item)
+		collection_docs = site.collections[item.collection.label].docs
+		collection_index = collection_docs.index { |document| document.equal?(item) }
+		return nil if collection_index.nil?
+
+		collection_docs.delete_at(collection_index)
+		{
+			'collection_label' => item.collection.label.to_s,
+			'index' => collection_index
+		}
+	end
+
 	# Logs one info-level summary line for each configured generate entry.
 	def log_generate_report(logger, generated_template_report)
 		report_entries = Utils.arrayify(generated_template_report['entries'])

data/lib/jekyll-paginate-v3/pagination/model/core.rb

@@ -160,6 +160,9 @@ class Model
 	# Captures the source items used by later `items` searches so
 	# pagination item resolution remains stable even after templates are
 	# removed and replaced by generated index pages.
+	#
+	# This frozen snapshot is the invariant that stops emitted pagination
+	# pages from feeding back into later item searches.
 	def capture_item_resolution_sources!
 		@item_resolution_pages = @site.pages.dup
 		@item_resolution_documents_by_collection = {}
@@ -436,9 +439,12 @@ class Model
 	# applies generic inclusion/exclusion flags.
 	#
 	# `exclude_items` is used by the pagination pipeline to remove the
-	# active source template from its own item set without also excluding
-	# other templates that the user may legitimately want to paginate over.
-	def resolve_items(raw_search, include_templates: false, include_generated_indexes: false, include_hidden: false, exclude_items: nil)
+	# active source template from its own item set while leaving other
+	# pagination templates eligible for ordinary item searches.
+	#
+	# Emitted pagination indexes are kept out by the frozen source items
+	# captured earlier in the pipeline, rather than by ad hoc filtering.
+	def resolve_items(raw_search, include_hidden: false, exclude_items: nil)
 		entries = Query::Parser.parse(raw_search, @site_config['keywords'], split_delimiter: @split_delimiter)
 		if entries.empty?
 			log("Resolving items from search=#{raw_search.inspect} produced no parsed entries.", 'debug')
@@ -446,7 +452,7 @@ class Model
 		end
 
 		excluded_item_keys = excluded_item_identity_keys(exclude_items)
-		log("Resolving items from search=#{raw_search.inspect} (entries=#{entries.length}, include_templates=#{include_templates}, include_generated_indexes=#{include_generated_indexes}, include_hidden=#{include_hidden}, exclude_items=#{excluded_item_keys.length}).", 'debug')
+		log("Resolving items from search=#{raw_search.inspect} (entries=#{entries.length}, include_hidden=#{include_hidden}, exclude_items=#{excluded_item_keys.length}).", 'debug')
 		resolved = []
 		entries.each do |entry|
 			resolved.concat(resolve_entry(entry))
@@ -457,18 +463,14 @@ class Model
 		log("Resolved #{resolved.length} unique item(s) before exclusion filters.", 'debug')
 		log_item_path_sample('Resolved item sample before exclusions', resolved)
 
-		excluded_generated_indexes = include_generated_indexes ? 0 : resolved.count { |item| Utils.generated_index?(item) }
-		excluded_templates = include_templates ? 0 : resolved.count { |item| Utils.pagination_template?(item) }
 		excluded_hidden = include_hidden ? 0 : resolved.count { |item| item['hidden'] }
 		excluded_explicit_items = excluded_item_keys.empty? ? 0 : resolved.count { |item| excluded_item_keys.include?(item_identity_key(item)) }
 
-		resolved.select! { |item| !Utils.generated_index?(item) } unless include_generated_indexes
-		resolved.select! { |item| !Utils.pagination_template?(item) } unless include_templates
 		resolved.select! { |item| !item['hidden'] } unless include_hidden
 		resolved.select! { |item| !excluded_item_keys.include?(item_identity_key(item)) } unless excluded_item_keys.empty?
 
-		if excluded_generated_indexes.positive? || excluded_templates.positive? || excluded_hidden.positive? || excluded_explicit_items.positive?
-			log("Excluded generated_indexes=#{excluded_generated_indexes} templates=#{excluded_templates} hidden=#{excluded_hidden} explicit=#{excluded_explicit_items} from resolved items.", 'debug')
+		if excluded_hidden.positive? || excluded_explicit_items.positive?
+			log("Excluded hidden=#{excluded_hidden} explicit=#{excluded_explicit_items} from resolved items.", 'debug')
 		end
 		log("Resolved #{resolved.length} item(s) after exclusion filters.", 'debug')
 		log_item_path_sample('Resolved item sample after exclusions', resolved)

data/lib/jekyll-paginate-v3/pagination/model/pagination_pipeline.rb

@@ -25,6 +25,7 @@ class Model
 
 		total_paginated_items = 0
 		total_indexes = 0
+		collection_replacement_state = nil
 
 		variants.each_with_index do |variant, variant_index|
 			variant_template = variant['template']
@@ -33,8 +34,10 @@ class Model
 				variant_template,
 				variant_config,
 				remove_source_template: variant_index.zero?,
-				item_exclusions: item_exclusions
+				item_exclusions: item_exclusions,
+				collection_replacement_state: collection_replacement_state
 			)
+			collection_replacement_state = variant_report['collection_replacement_state']
 			total_paginated_items += variant_report['paginated_items'].to_i
 			total_indexes += variant_report['indexes'].to_i
 		end
@@ -46,9 +49,8 @@ class Model
 	end
 
 	# Returns the per-template item exclusions required to prevent a
-	# template from paginating over itself when the active item object is
-	# still otherwise eligible during resolution. Other pagination
-	# templates remain excluded by normal item-resolution rules.
+	# template from paginating over itself when pagination templates are
+	# otherwise eligible during item resolution.
 	def pagination_item_exclusions_for_template(template)
 		[template]
 	end
@@ -80,7 +82,7 @@ class Model
 	end
 
 	# Runs pagination for one already-expanded template variant.
-	def paginate_template_variant(template, config, remove_source_template:, item_exclusions:)
+	def paginate_template_variant(template, config, remove_source_template:, item_exclusions:, collection_replacement_state:)
 		template_path = Utils.relative_item_path(template)
 		split_delimiter = config.key?('split') ? config['split'] : @split_delimiter
 		nested_separator = config['separator'] || @nested_separator
@@ -128,23 +130,30 @@ class Model
 		validate_numbered_permalink_template!(template, config, total_pages)
 
 		log("Template '#{template_path}': generating #{total_pages} page(s) with per_page=#{config['per_page']} limit=#{config['limit']}.", 'debug')
-		generated_pages = emit_paginated_pages(
+		page_emission = emit_paginated_pages(
 			template,
 			config,
 			sorted_items,
 			page_windows,
-			remove_template: remove_source_template
+			remove_template: remove_source_template,
+			collection_replacement_state: collection_replacement_state
 		)
+		generated_pages = page_emission['pages']
+		collection_replacement_state = page_emission['collection_replacement_state']
 		register_grouped_set_if_applicable(template, config, generated_pages)
 		{
 			'paginated_items' => sorted_items.length,
-			'indexes' => generated_pages.length
+			'indexes' => generated_pages.length,
+			'collection_replacement_state' => collection_replacement_state
 		}
 	end
 
 	# Replaces a template with one synthetic page/document per page number.
-	def emit_paginated_pages(template, config, items, page_windows, remove_template: true)
-		@remove_item_lambda.call(template) if remove_template
+	def emit_paginated_pages(template, config, items, page_windows, remove_template: true, collection_replacement_state: nil)
+		if remove_template
+			removed_item_state = @remove_item_lambda.call(template)
+			collection_replacement_state = build_collection_replacement_state(template, removed_item_state)
+		end
 
 		new_pages = []
 		total_pages = page_windows.length
@@ -192,14 +201,50 @@ class Model
 			assign_generated_page_title!(generated, template, config, current_page, total_pages)
 			assign_generated_page_permalink!(generated, template, config, current_page, total_pages)
 
-			@add_item_lambda.call(generated)
+			@add_item_lambda.call(
+				generated,
+				collection_index: collection_insertion_index_for_generated_item(generated, collection_replacement_state)
+			)
 			log("Emitted pagination page #{current_page}/#{total_pages} at '#{generated.url}' for template '#{Utils.relative_item_path(template)}'.", 'debug')
 			new_pages << generated
 		end
 
 		bind_paginator_references(new_pages)
 		apply_page_trail(new_pages, config)
-		new_pages
+		{
+			'pages' => new_pages,
+			'collection_replacement_state' => collection_replacement_state
+		}
+	end
+
+	# Builds insertion state for collection-template replacement.
+	#
+	# The state stores a moving insertion cursor so any generated
+	# collection documents can occupy the template's original source slot
+	# and then continue immediately after it.
+	def build_collection_replacement_state(template, removed_item_state)
+		return nil unless collection_template?(template)
+
+		removed_item_state = Utils.safe_hash(removed_item_state)
+		return nil if removed_item_state.empty?
+		return nil if removed_item_state['collection_label'].to_s != template.collection.label.to_s
+
+		{
+			'source_collection_label' => template.collection.label.to_s,
+			'next_index' => removed_item_state['index'].to_i
+		}
+	end
+
+	# Returns the next insertion index for a generated document that
+	# belongs in the same collection as the template it replaced.
+	def collection_insertion_index_for_generated_item(generated, collection_replacement_state)
+		return nil if collection_replacement_state.nil?
+		return nil unless generated.is_a?(Jekyll::Document)
+		return nil if generated.collection.label.to_s != collection_replacement_state['source_collection_label'].to_s
+
+		insertion_index = collection_replacement_state['next_index'].to_i
+		collection_replacement_state['next_index'] = insertion_index + 1
+		insertion_index
 	end
 
 	# Builds one generated index object according to configured collection mode.

data/lib/jekyll-paginate-v3/version.rb

@@ -4,7 +4,7 @@ module Jekyll
 module Plugins
 
 module PaginateV3
-	VERSION = '0.1.0.alpha'
+	VERSION = '0.1.0.alpha.2'
 end
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-paginate-v3
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha
+  version: 0.1.0.alpha.2
 platform: ruby
 authors:
 - Convincible
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-24 00:00:00.000000000 Z
+date: 2026-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll