jekyll-paginate-v3 0.1.0.alpha.3 → 0.2.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4167a9c3e76eb08e45275f31be52227e30a6b6d453f1bceef0c901097d4250f7
-  data.tar.gz: e8e96586a43ff094865264446fc5389555438c74e87dbeb38f5c0c818b2ed47e
+  metadata.gz: 800113e7a994aa5e6b1a85ec42a7af7a2d14af9c47e8ad9db98de54763b4b6db
+  data.tar.gz: d1e054fdd4621e09fb37f36d98c7009d6d8891e12ce485ef3d6fc0bb3aa7aa99
 SHA512:
-  metadata.gz: 457fc67c2920f51aac38003b395720365df59f5786a9fb71f1d34c6d68d5a279abb32f10608b3d4c2c66b93934f8108e26175165795bb4a253c43898eb89d12d
-  data.tar.gz: a44bb5a0591d319502f0f574d5fa0493a4636477e7a8301ba9a9c5fc712b74f1564b169617b15c950512f52f29d2a23d3b6207c86b8d09cddbd182f81e4fdca3
+  metadata.gz: 9a955153959b071277e958f5b6d24518a49295b401edd2fc15ee74f282e85e4f3ca5af6ae1be61a5b8af0c72b2a9163d49e6ee4214df11886609c56c29363e9b
+  data.tar.gz: 56c0a857ce7e8275c5f4081b427bf6dd6e79ff2ab571cb6446a4d8901c5cc0229c416ed263a9ed497d1737149556dc181b8ef37337209fec743dfa347287f776

data/lib/jekyll-paginate-v3/config/defaults.rb

@@ -41,6 +41,10 @@ module Config
 		'clone' => COLLECTION_TARGET_CLONE
 	}.freeze
 
+	# Slugification modes exposed by pagination config. Every supported mode
+	# must produce a route key rather than bypassing character filtering.
+	SLUGIFY_MODES = %w[default ascii latin].freeze
+
 	DEFAULTS = {
 		'enabled' => true,
 		'compatibility' => nil,
@@ -62,8 +66,8 @@ module Config
 		'limit' => 0,
 		'offset' => 0,
 		'trail' => 5,
-		'title' => ':title - :num',
-		'permalink' => ':num',
+		'title' => '{{ title }} - {{ num }}',
+		'permalink' => '{{ num }}',
 		'layout' => nil,
 		'layouts' => [],
 		'group' => nil,
@@ -96,7 +100,7 @@ module Config
 			},
 			'items' => 'posts',
 			'title' => ':title - page :num',
-			'permalink' => '/page/:num/',
+			'permalink' => 'page/:num/',
 			'trail' => {
 				'before' => 2,
 				'after' => 2

data/lib/jekyll-paginate-v3/config/normaliser/legacy_compatibility.rb

@@ -43,7 +43,7 @@ class Normaliser
 			extension = override_hash.key?('extension') ? override_hash['extension'].to_s : 'html'
 
 			template_config['page_templates'] ||= build_page_templates(template_config['title'], template_config['permalink'])
-			template_config['page_templates']['page1']['permalink'] = Utils.ensure_full_path('/', index_name, extension)
+			template_config['page_templates']['page1']['permalink'] = Utils.ensure_full_path(index_name, index_name, extension)
 			template_config['page_templates']['page2']['permalink'] = Utils.ensure_full_path(template_config['permalink'], index_name, extension)
 		end
 
@@ -118,11 +118,9 @@ class Normaliser
 			permalink = group['permalink']
 			permalink = defaults['permalink'] unless present_config_value?(permalink)
 
-			slugify = if group.key?('slugify')
-									Utils.safe_hash(group['slugify'])
-								else
-									Utils.deep_copy(defaults['slugify'])
-								end
+			slugify = normalise_slugify_config(
+				group.key?('slugify') ? group['slugify'] : Utils.deep_copy(defaults['slugify'])
+			)
 
 			[
 				{

data/lib/jekyll-paginate-v3/config/normaliser/site_and_templates.rb

@@ -199,9 +199,9 @@ class Normaliser
 			# does not make the default location collide with a collection label.
 			source['location'] = keywords['pages'] if source['location'].nil? || source['location'].to_s.strip.empty?
 			source['generate'] = if source['generate'].is_a?(Array)
-										source['generate'].map { |entry| Utils.safe_hash(entry) }
+										source['generate'].map { |entry| normalise_generated_template_definition(entry) }
 									elsif source['generate'].is_a?(Hash)
-										[Utils.safe_hash(source['generate'])]
+										[normalise_generated_template_definition(source['generate'])]
 									else
 										[]
 									end
@@ -212,6 +212,17 @@ class Normaliser
 			source
 		end
 
+		# Validates settings that generated templates otherwise would not
+		# normalise until their in-memory template objects are processed.
+		def normalise_generated_template_definition(raw_definition)
+			definition = Utils.safe_hash(raw_definition)
+			if definition.key?('slugify')
+				definition['slugify'] = normalise_slugify_config(definition['slugify'])
+			end
+
+			definition
+		end
+
 		# Returns site-level defaults that are inherited by explicit and
 		# generated templates.
 		def extract_site_template_defaults(site_config)
@@ -382,7 +393,7 @@ class Normaliser
 		def build_page_templates(page2_title, page2_permalink)
 			{
 				'page1' => {
-					'title' => ':title',
+					'title' => '{{ title }}',
 					'permalink' => ''
 				},
 				'page2' => {
@@ -454,7 +465,7 @@ class Normaliser
 		# Preserves legacy `sort_field` + `sort_reverse` behaviour when the
 		# caller did not provide an explicit `sort` override.
 		def normalise_sort(raw_sort, raw_sort_field, raw_sort_reverse, split_delimiter, sort_explicitly_set: false)
-			sort_entries = Utils.arrayify(raw_sort, split_delimiter: split_delimiter).map(&:to_s).map(&:strip).reject(&:empty?)
+			sort_entries = placeholder_aware_sort_entries(raw_sort, split_delimiter)
 			sort_field = raw_sort_field.to_s.strip
 
 			if !sort_explicitly_set && !sort_field.empty?
@@ -466,13 +477,25 @@ class Normaliser
 
 			if sort_field.empty?
 				fallback_sort = DEFAULTS['sort']
-				return Utils.arrayify(fallback_sort, split_delimiter: split_delimiter).map(&:to_s).map(&:strip).reject(&:empty?)
+				return placeholder_aware_sort_entries(fallback_sort, split_delimiter)
 			end
 
 			direction = boolean_config_value(raw_sort_reverse) ? 'desc' : 'asc'
 			["#{sort_field} #{direction}"]
 		end
 
+		# Splits sort lists without treating a canonical placeholder filter pipe
+		# as the configured list separator.
+		def placeholder_aware_sort_entries(raw_sort, split_delimiter)
+			raw_entries = raw_sort.is_a?(Array) ? raw_sort.flatten : [raw_sort]
+			raw_entries.flat_map do |raw_entry|
+				Support::PlaceholderTemplate.split_source(
+					raw_entry,
+					delimiter: split_delimiter
+				)
+			end.map(&:to_s).map(&:strip).reject(&:empty?)
+		end
+
 		# Normalises `pagination.layout` / `pagination.layouts` into a
 		# canonical string array.
 		def normalise_layout_overrides(config, split_delimiter:)
@@ -499,9 +522,17 @@ class Normaliser
 								[raw_group]
 							end
 
-			raw_entries.map do |raw_entry|
+			entries = raw_entries.map do |raw_entry|
 				normalise_group_entry(raw_entry)
 			end.compact
+
+			keys = entries.map { |entry| entry['on'].to_s }
+			duplicate_keys = keys.group_by(&:itself).select { |_, matches| matches.length > 1 }.keys
+			unless duplicate_keys.empty?
+				raise ArgumentError, "Duplicate pagination group key(s): #{duplicate_keys.sort.join(', ')}. Each `group.on` key must be unique."
+			end
+
+			entries
 		end
 
 		# Normalises legacy `index` + `group` + `filter` config into modern
@@ -571,26 +602,25 @@ class Normaliser
 			{ 'on' => on_key }
 		end
 
-		# Normalises slugify config accepted on template pagination config.
-		# This supports `slugify.lowercase` semantics while also allowing
-		# string shorthand where the value maps directly to `mode`.
+		# Normalises slugify config into the route-key policy shared by grouping
+		# and slugified placeholder representations.
 		def normalise_slugify_config(raw_slugify)
-			if raw_slugify.is_a?(String)
-				mode = raw_slugify.to_s.strip
-				mode = 'default' if mode.empty?
-				return {
-					'mode' => mode,
-					'lowercase' => true
-				}
-			end
-
-			slugify = Utils.safe_hash(raw_slugify)
+			slugify = raw_slugify.is_a?(String) ? { 'mode' => raw_slugify } : Utils.safe_hash(raw_slugify)
 			mode = slugify['mode'].to_s.strip
 			mode = 'default' if mode.empty?
+			unless SLUGIFY_MODES.include?(mode)
+				raise ArgumentError, "`slugify.mode` must be one of #{SLUGIFY_MODES.join(', ')}; received '#{mode}'."
+			end
+
+			lowercase = if slugify.key?('lowercase')
+								boolean_config_value(slugify['lowercase'])
+							else
+								true
+							end
 
 			{
 				'mode' => mode,
-				'lowercase' => boolean_config_value(slugify['lowercase'])
+				'lowercase' => lowercase
 			}
 		end
 

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

@@ -72,8 +72,6 @@ class Model
 				end
 				next
 			end
-			validate_required_template_config!(template, template_config)
-
 			enabled_templates << [template, template_config, template_pagination_source, template_log_lambda]
 		end
 
@@ -177,9 +175,28 @@ class Model
 		)
 	end
 
+	# Keeps the captured item-resolution view immutable when a source
+	# template itself is retained and mutated into pagination page one.
+	# Later templates should still see the source template metadata rather
+	# than the emitted index metadata attached to the retained object.
+	def replace_item_resolution_source!(source_item, source_snapshot)
+		@item_resolution_pages&.map! do |item|
+			item.equal?(source_item) ? source_snapshot : item
+		end
+
+		@item_resolution_documents_by_collection&.each_value do |documents|
+			documents.map! do |item|
+				item.equal?(source_item) ? source_snapshot : item
+			end
+		end
+	end
+
 	# Discovers all pages/documents configured as pagination templates.
 	def discover_templates
 		search_entries = Query::Parser.parse(@site_config.dig('templates', 'location'), @site_config['keywords'], split_delimiter: @split_delimiter)
+		# Report site pages before collection sources regardless of configuration order.
+		page_search_entries, collection_search_entries = search_entries.partition { |entry| entry['type'] == Query::Parser::SEARCH_TYPE_PAGES }
+		search_entries = page_search_entries + collection_search_entries
 		reset_template_search_reporting_state
 
 		combined_candidates = []
@@ -321,10 +338,11 @@ class Model
 	def find_layout(layout_name)
 		layout = @site.layouts[layout_name]
 		return layout unless layout.nil?
-		return nil unless layout_name.include?('.')
 
-		basename = File.basename(layout_name, File.extname(layout_name))
-		@site.layouts[basename]
+		normalised_layout_name = Utils.normalise_layout_name(layout_name)
+		return nil if normalised_layout_name == layout_name
+
+		@site.layouts[normalised_layout_name]
 	end
 
 	# Resolves template compatibility mode from local and site config.

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

@@ -94,9 +94,14 @@ class Model
 	def grouped_set_sort_direction(config, index_key)
 		return 'asc' if index_key.to_s.strip.empty?
 
-		split_delimiter = config.key?('split') ? config['split'] : @split_delimiter
-		sort_instructions = Query::Sorter.parse(config['sort'], split_delimiter: split_delimiter)
-		sort_entry = sort_instructions.find { |entry| entry['field'] == index_key }
+		sort_instructions = config['_sort_instructions']
+		if sort_instructions.nil?
+			split_delimiter = config.key?('split') ? config['split'] : @split_delimiter
+			sort_instructions = Query::Sorter.parse(config['sort'], split_delimiter: split_delimiter)
+		end
+		sort_entry = sort_instructions.find do |entry|
+			(entry['source_field'] || entry['field']) == index_key
+		end
 		return 'asc' if sort_entry.nil?
 
 		sort_entry['direction']
@@ -115,33 +120,61 @@ class Model
 
 	# Applies configured page title templates.
 	def assign_generated_page_title!(generated, template, config, current_page, total_pages)
-		page_template = page_template_config(config, current_page)
 		base_title = template.data['title'] || @site.config['title']
-		generated.data['title'] = Utils.format_page_title(page_template['title'], base_title, current_page, total_pages)
+		pattern = page_placeholder_template(config, current_page, 'title')
+		generated.data['title'] = Utils.format_page_title(
+			pattern,
+			base_title,
+			current_page,
+			total_pages,
+			slugifier: placeholder_slugifier(config)
+		)
 	end
 
 	# Applies configured page permalink templates.
 	def assign_generated_page_permalink!(generated, template, config, current_page, total_pages)
-		resolved_permalink = resolved_page_permalink(template, config, current_page, total_pages)
+		page_route_fragment = resolved_page_route_fragment(config, current_page, total_pages)
+		page_route_path = Utils.join_route_fragments(page_route_fragment)
+		resolved_permalink = resolved_page_permalink(template, config, current_page, page_route_fragment)
+		reset_cached_item_url!(generated)
 
 		if resolved_permalink.nil?
 			generated.data.delete('permalink') if current_page > 1
-			return
+			return page_route_path
 		end
 
-		generated.data['permalink'] = resolved_permalink
+		context = "pagination page #{current_page} for template '#{Utils.relative_item_path(template)}'"
+		generated.data['permalink'] = Utils.validate_resolved_permalink!(resolved_permalink, context: context)
+		Utils.validate_output_destination!(generated, site: @site, context: context)
+		page_route_path
 	end
 
-	# Resolves one page permalink from page1/page2 template settings.
-	def resolved_page_permalink(template, config, current_page, total_pages)
-		page_template = page_template_config(config, current_page)
-		template_permalink = Utils.format_page_number(page_template['permalink'], current_page, total_pages)
-		return Utils.ensure_leading_slash(template_permalink) if v1_absolute_paginate_path?(config, current_page)
+	# Resolves the relative route fragment contributed by the current index.
+	def resolved_page_route_fragment(config, current_page, total_pages)
+		pattern = page_placeholder_template(config, current_page, 'permalink')
+		Utils.format_page_number(
+			pattern,
+			current_page,
+			total_pages,
+			slugifier: placeholder_slugifier(config)
+		)
+	end
+
+	# Resolves one complete page permalink from the template route and already
+	# interpolated page fragment.
+	def resolved_page_permalink(template, config, current_page, page_route_fragment)
+		return Utils.ensure_leading_slash(page_route_fragment) if v1_absolute_paginate_path?(config, current_page)
 
 		first_page_url = template_first_page_url(template)
-		return first_page_url if template_permalink.to_s.strip.empty?
+		return first_page_url if page_route_fragment.to_s.strip.empty?
+
+		join_url(first_page_url, page_route_fragment)
+	end
 
-		join_url(first_page_url, template_permalink)
+	# Clears Jekyll's memoised URL before a retained source object receives its
+	# final permalink. Generated adapters already start with an empty cache.
+	def reset_cached_item_url!(item)
+		item.instance_variable_set(:@url, nil) if item.instance_variable_defined?(:@url)
 	end
 
 	# Determines whether this page should use v1-style absolute paginate_path.
@@ -161,7 +194,7 @@ class Model
 
 		if current_page == 1
 			{
-				'title' => ':title',
+				'title' => '{{ title }}',
 				'permalink' => ''
 			}
 		else
@@ -172,15 +205,42 @@ class Model
 		end
 	end
 
-	# Ensures multi-page pagination outputs include `:num` in page2 permalink
+	# Returns the already-parsed pattern for one page-template field, falling
+	# back to its public scalar for compatibility callers without variant state.
+	def page_placeholder_template(config, current_page, field)
+		key = current_page == 1 ? 'page1' : 'page2'
+		parsed = config.dig('_placeholder_templates', 'page_templates', key, field)
+		return parsed unless parsed.nil?
+
+		page_template_config(config, current_page)[field]
+	end
+
+	# Builds the representation filter used by system values in this template.
+	def placeholder_slugifier(config)
+		slugify = Utils.safe_hash(config['slugify'])
+		mode = slugify['mode'].to_s.strip
+		mode = 'default' if mode.empty?
+		lowercase = !!slugify['lowercase']
+		lambda do |value|
+			Jekyll::Utils.slugify(value.to_s, mode: mode, cased: !lowercase)
+		end
+	end
+
+	# Ensures multi-page pagination outputs include a page-number placeholder
 	# templates so each generated index resolves to a unique destination path.
 	def validate_numbered_permalink_template!(template, config, total_pages)
 		return unless total_pages > 1
 
 		page2_permalink = page_template_config(config, 2)['permalink'].to_s
-		return if page2_permalink.include?(':num')
-
-		raise ArgumentError, "Template '#{Utils.relative_item_path(template)}' paginates to #{total_pages} pages but page2 permalink template '#{page2_permalink}' (from `pagination.page_templates.page2.permalink` or fallback `pagination.permalink`) does not include ':num'. Add ':num' so generated indexes have unique permalinks."
+		parsed_permalink = page_placeholder_template(config, 2, 'permalink')
+		parsed_permalink = Utils.placeholder_template(
+			page2_permalink,
+			allowed: %w[num max],
+			context: 'pagination page2 permalink'
+		) unless parsed_permalink.is_a?(Support::PlaceholderTemplate)
+		return if parsed_permalink.include_placeholder?('num')
+
+		raise ArgumentError, "Template '#{Utils.relative_item_path(template)}' paginates to #{total_pages} pages but page2 permalink template '#{page2_permalink}' (from `pagination.page_templates.page2.permalink` or fallback `pagination.permalink`) does not include '{{ num }}' or ':num'. Add a page-number placeholder so generated indexes have unique permalinks."
 	end
 
 	# Determines the canonical URL for the first pagination page of a template.

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

@@ -14,9 +14,17 @@ class Model
 	
 	def paginate_template(template, config, template_pagination_source)
 		item_exclusions = pagination_item_exclusions_for_template(template)
-		variants = expand_template_variants(template, config, template_pagination_source: template_pagination_source, item_exclusions: item_exclusions)
+		template_route = template_first_page_url(template)
+		variants = expand_template_variants(
+			template,
+			config,
+			template_route: template_route,
+			template_pagination_source: template_pagination_source,
+			item_exclusions: item_exclusions
+		)
 		if variants.empty?
-			log("Template '#{Utils.relative_item_path(template)}': grouping/layout expansion produced no variants.", 'debug')
+			@remove_item_lambda.call(template)
+			log("Template '#{Utils.relative_item_path(template)}': grouping/layout expansion produced no variants; consumed template without emitting indexes.", 'debug')
 			return {
 				'paginated_items' => 0,
 				'indexes' => 0
@@ -26,6 +34,7 @@ class Model
 		total_paginated_items = 0
 		total_indexes = 0
 		collection_replacement_state = nil
+		retain_page_one = variants.one? && retain_source_template_as_page_one?(template, variants.first['config'])
 
 		variants.each_with_index do |variant, variant_index|
 			variant_template = variant['template']
@@ -33,7 +42,10 @@ class Model
 			variant_report = paginate_template_variant(
 				variant_template,
 				variant_config,
-				remove_source_template: variant_index.zero?,
+				remove_source_template: variant_index.zero? && !retain_page_one,
+				retain_page_one: retain_page_one,
+				route_base: variant['route_base'],
+				route_path: variant['route_path'],
 				item_exclusions: item_exclusions,
 				collection_replacement_state: collection_replacement_state
 			)
@@ -56,34 +68,28 @@ class Model
 	end
 
 	# Expands one template into grouped/layout variants before pagination.
-	def expand_template_variants(template, config, template_pagination_source:, item_exclusions:)
+	def expand_template_variants(template, config, template_route:, template_pagination_source:, item_exclusions:)
 		expander = Templates::VariantExpander.new(
 			site: @site,
 			site_config: @site_config,
 			template: template,
+			template_route: template_route,
 			template_config: config,
 			template_pagination_source: template_pagination_source,
 			merge_template_pagination_lambda: method(:merged_template_pagination_config),
 			normalise_template_config_lambda: lambda { |pagination| Config::Normaliser.normalise_template_config(@site_config, pagination) },
+			validate_template_config_lambda: method(:validate_required_template_config!),
 			resolve_items_lambda: lambda { |raw_search| resolve_items(raw_search, exclude_items: item_exclusions) },
 			log_lambda: @active_log_lambda
 		)
-		variants = expander.expand
-		return variants unless variants.empty?
-
-		template.data['pagination'] = merged_template_pagination_config(template, template_pagination_source)
-
-		[
-			{
-				'template' => template,
-				'config' => config
-			}
-		]
+		expander.expand
 	end
 
 	# Runs pagination for one already-expanded template variant.
-	def paginate_template_variant(template, config, remove_source_template:, item_exclusions:, collection_replacement_state:)
+	def paginate_template_variant(template, config, remove_source_template:, retain_page_one:, route_base:, route_path:, item_exclusions:, collection_replacement_state:)
 		template_path = Utils.relative_item_path(template)
+		emission_template = retain_page_one ? clone_template_for_emission(template) : template
+		replace_item_resolution_source!(template, emission_template) if retain_page_one
 		split_delimiter = config.key?('split') ? config['split'] : @split_delimiter
 		nested_separator = config['separator'] || @nested_separator
 		all_items = resolve_items(config['items'], exclude_items: item_exclusions)
@@ -108,7 +114,8 @@ class Model
 			config['sort'],
 			nested_separator: nested_separator,
 			equivalents: @equivalents,
-			split_delimiter: split_delimiter
+			split_delimiter: split_delimiter,
+			instructions: config['_sort_instructions']
 		)
 		log("Template '#{template_path}': sorted #{sorted_items.length} item(s) by #{config['sort']} before offset.", 'debug')
 		log_item_path_sample("Template '#{template_path}': sorted item sample", sorted_items)
@@ -127,20 +134,23 @@ class Model
 
 		page_windows = Utils.build_pagination_windows(sorted_items.length, config['per_page'])
 		total_pages = page_windows.length
-		validate_numbered_permalink_template!(template, config, total_pages)
+		validate_numbered_permalink_template!(emission_template, config, total_pages)
 
 		log("Template '#{template_path}': generating #{total_pages} page(s) with per_page=#{config['per_page']} limit=#{config['limit']}.", 'debug')
 		page_emission = emit_paginated_pages(
-			template,
+			emission_template,
 			config,
 			sorted_items,
 			page_windows,
 			remove_template: remove_source_template,
+			retained_page_one: retain_page_one ? template : nil,
+			route_base: route_base,
+			route_path: route_path,
 			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)
+		register_grouped_set_if_applicable(emission_template, config, generated_pages)
 		{
 			'paginated_items' => sorted_items.length,
 			'indexes' => generated_pages.length,
@@ -149,10 +159,12 @@ class Model
 	end
 
 	# Replaces a template with one synthetic page/document per page number.
-	def emit_paginated_pages(template, config, items, page_windows, remove_template: true, collection_replacement_state: nil)
+	def emit_paginated_pages(template, config, items, page_windows, remove_template: true, retained_page_one: nil, route_base:, route_path:, 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)
+		elsif !retained_page_one.nil?
+			collection_replacement_state = build_retained_collection_insertion_state(retained_page_one)
 		end
 
 		new_pages = []
@@ -164,13 +176,18 @@ class Model
 
 		page_windows.each do |page_window|
 			current_page = page_window['num']
-			generated = build_generated_item(
-				template: template,
-				config: config,
-				current_page: current_page,
-				total_pages: total_pages,
-				index_file: index_file
-			)
+			retaining_current_page = current_page == 1 && !retained_page_one.nil?
+			generated = if retaining_current_page
+							prepare_retained_page_one(retained_page_one, current_page: current_page, total_pages: total_pages)
+						else
+							build_generated_item(
+								template: template,
+								config: config,
+								current_page: current_page,
+								total_pages: total_pages,
+								index_file: index_file
+							)
+						end
 
 			generated.pager = Paginator.new(
 				per_page: config['per_page'],
@@ -199,13 +216,18 @@ class Model
 			generated.data['autogen'] = 'jekyll-paginate-v2' if config['compatibility'] == 'v2'
 
 			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,
-				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')
+			page_route_path = assign_generated_page_permalink!(generated, template, config, current_page, total_pages)
+			generated.data['pagination']['base'] = Utils.normalise_route(route_base)
+			generated.data['pagination']['path'] = Utils.join_route_fragments(route_path, page_route_path)
+
+			unless retaining_current_page
+				@add_item_lambda.call(
+					generated,
+					collection_index: collection_insertion_index_for_generated_item(generated, collection_replacement_state)
+				)
+			end
+			action = retaining_current_page ? 'Retained' : 'Emitted'
+			log("#{action} pagination page #{current_page}/#{total_pages} at '#{generated.url}' for template '#{Utils.relative_item_path(template)}'.", 'debug')
 			new_pages << generated
 		end
 
@@ -217,6 +239,32 @@ class Model
 		}
 	end
 
+	# Reuses an eligible source page/document while adding the small runtime
+	# interface and metadata normally supplied by generated subclasses.
+	def prepare_retained_page_one(item, current_page:, total_pages:)
+		item.extend(Pages::PagerSupport) unless item.respond_to?(:pager=)
+		item.data['pagination_info'] = {
+			'curr_page' => current_page,
+			'total_pages' => total_pages
+		}
+		item
+	end
+
+	# Clones mutable template presentation state before page one is updated in
+	# place, keeping all later page emission based on the original variant.
+	def clone_template_for_emission(template)
+		cloned_template = template.dup
+		# Keep the retained source independent from the snapshot used to emit its later pages.
+		cloned_data = Utils.deep_copy(Utils.safe_hash(template.data))
+		if cloned_template.respond_to?(:data=)
+			cloned_template.data = cloned_data
+		else
+			cloned_template.instance_variable_set(:@data, cloned_data)
+		end
+		cloned_template.content = template.content.to_s if cloned_template.respond_to?(:content=)
+		cloned_template
+	end
+
 	# Builds insertion state for collection-template replacement.
 	#
 	# The state stores a moving insertion cursor so any generated
@@ -235,6 +283,21 @@ class Model
 		}
 	end
 
+	# Starts insertion immediately after a retained source document so later
+	# self-targeted indexes preserve collection ordering without remove/re-add.
+	def build_retained_collection_insertion_state(template)
+		return nil unless collection_template?(template)
+
+		collection_documents = template.collection.docs
+		template_index = collection_documents.index { |document| document.equal?(template) }
+		return nil if template_index.nil?
+
+		{
+			'source_collection_label' => template.collection.label.to_s,
+			'next_index' => template_index + 1
+		}
+	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)
@@ -313,6 +376,16 @@ class Model
 		Config::COLLECTION_TARGET_SHADOW
 	end
 
+	# Determines whether page one can keep the source object's exact identity
+	# while honouring the effective output target.
+	def retain_source_template_as_page_one?(template, config)
+		target_mode = collection_target_mode_for_page(template, config, 1)
+		return target_mode == Config::COLLECTION_TARGET_SELF if template.is_a?(Jekyll::Document)
+		return target_mode == Config::COLLECTION_TARGET_PAGES if template.is_a?(Jekyll::Page)
+
+		false
+	end
+
 	# Returns true when a template is a collection document.
 	def collection_template?(template)
 		template.is_a?(Jekyll::Document)