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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 036fbbfba18f61ae73a069e4330fce833a1cb7549704c9bf396961ddd262569f
-  data.tar.gz: 061d674f1bfd29de53bb79bc5a64feb8076a80af38f59be877f3cc77443173ff
+  metadata.gz: 800113e7a994aa5e6b1a85ec42a7af7a2d14af9c47e8ad9db98de54763b4b6db
+  data.tar.gz: d1e054fdd4621e09fb37f36d98c7009d6d8891e12ce485ef3d6fc0bb3aa7aa99
 SHA512:
-  metadata.gz: e6561b1d072672dabdbace597b3b7d310a3f357f7d9b05a1f6815d7b29e634029faf7828ca8105edf6cc41fd1cab276e215de8343358c53e42b482e005f64235
-  data.tar.gz: 259bd8d452c747203d316a977de290141b11bc1061a39386e0bac81733f1ace2b08ef0b9c1d8092212e232544bb6f8f758e2e49327b6779f54116e555213a7d4
+  metadata.gz: 9a955153959b071277e958f5b6d24518a49295b401edd2fc15ee74f282e85e4f3ca5af6ae1be61a5b8af0c72b2a9163d49e6ee4214df11886609c56c29363e9b
+  data.tar.gz: 56c0a857ce7e8275c5f4081b427bf6dd6e79ff2ab571cb6446a4d8901c5cc0229c416ed263a9ed497d1737149556dc181b8ef37337209fec743dfa347287f776

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

@@ -27,6 +27,24 @@ module Config
 		'items' => 'items'
 	}.freeze
 
+	# Internal collection-mode identifiers. These never appear in user
+	# configuration, which lets a renamed keyword release its original word for
+	# use as a real Jekyll collection label.
+	COLLECTION_TARGET_PAGES = '__paginate_v3_collection_target_pages__'.freeze
+	COLLECTION_TARGET_SELF = '__paginate_v3_collection_target_self__'.freeze
+	COLLECTION_TARGET_SHADOW = '__paginate_v3_collection_target_shadow__'.freeze
+	COLLECTION_TARGET_CLONE = '__paginate_v3_collection_target_clone__'.freeze
+	COLLECTION_TARGET_BY_KEY = {
+		'pages' => COLLECTION_TARGET_PAGES,
+		'self' => COLLECTION_TARGET_SELF,
+		'shadow' => COLLECTION_TARGET_SHADOW,
+		'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,
@@ -41,15 +59,15 @@ module Config
 			['category', 'categories']
 		],
 		'items' => nil,
-		'collection' => ['self', 'shadow'],
+		'collection' => [COLLECTION_TARGET_SELF, COLLECTION_TARGET_SHADOW],
 		'filters' => nil,
 		'sort' => 'date desc',
 		'per_page' => 10,
 		'limit' => 0,
 		'offset' => 0,
 		'trail' => 5,
-		'title' => ':title - :num',
-		'permalink' => ':num',
+		'title' => '{{ title }} - {{ num }}',
+		'permalink' => '{{ num }}',
 		'layout' => nil,
 		'layouts' => [],
 		'group' => nil,
@@ -58,7 +76,7 @@ module Config
 			'lowercase' => true
 		},
 		'templates' => {
-			'location' => 'pages',
+			'location' => nil,
 			'generate' => []
 		}
 	}.freeze
@@ -82,7 +100,7 @@ module Config
 			},
 			'items' => 'posts',
 			'title' => ':title - page :num',
-			'permalink' => '/page/:num/',
+			'permalink' => 'page/:num/',
 			'trail' => {
 				'before' => 2,
 				'after' => 2
@@ -95,7 +113,6 @@ module Config
 			},
 			'items' => 'posts',
 			'templates' => {
-				'location' => 'pages',
 				'generate' => []
 			}
 		}

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
 
@@ -72,26 +72,28 @@ class Normaliser
 			autopages = Utils.safe_hash(raw_autopages)
 			return if autopages.empty? || autopages['enabled'] == false
 
+			# Use the effective search keyword because compatibility profiles may rename `all` and release the original word for use as a collection label.
+			all_items_keyword = config.dig('keywords', 'all')
 			migrated = []
 
 			migrated.concat(migrate_v2_autopage_group(
 												raw_group: autopages['tags'],
 												index_key: 'tag',
-												items: 'all',
+												items: all_items_keyword,
 												defaults: V2_AUTOPAGE_DEFAULTS['tags'],
 												split_delimiter: config.dig('syntax', 'split')
 											))
 			migrated.concat(migrate_v2_autopage_group(
 												raw_group: autopages['categories'],
 												index_key: 'category',
-												items: 'all',
+												items: all_items_keyword,
 												defaults: V2_AUTOPAGE_DEFAULTS['categories'],
 												split_delimiter: config.dig('syntax', 'split')
 											))
 			migrated.concat(migrate_v2_autopage_group(
 												raw_group: autopages['collections'],
 												index_key: 'collection',
-												items: 'all',
+												items: all_items_keyword,
 												defaults: V2_AUTOPAGE_DEFAULTS['collections'],
 												split_delimiter: config.dig('syntax', 'split')
 											))
@@ -116,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

@@ -58,7 +58,8 @@ class Normaliser
 			config['equivalents'] = normalise_equivalents(config['equivalents'], split_delimiter)
 			config['templates'] = normalise_templates(
 				config['templates'],
-				split_delimiter: split_delimiter
+				split_delimiter: split_delimiter,
+				keywords: config['keywords']
 			)
 
 			normalised_template_defaults = normalise_template_defaults(
@@ -188,17 +189,19 @@ class Normaliser
 		# Connects to: the surrounding pagination flow in this file.
 		# Params: `raw_templates`, `split_delimiter`.
 		# Returns: a value consumed by the next pipeline step.
-		def normalise_templates(raw_templates, split_delimiter:)
+		def normalise_templates(raw_templates, split_delimiter:, keywords:)
 			defaults = Utils.deep_copy(DEFAULTS['templates'])
 			source_hash = Utils.safe_hash(raw_templates)
 			source = defaults.merge(source_hash)
 			source.delete('defaults')
 
-			source['location'] = defaults['location'] if source['location'].nil? || source['location'].to_s.strip.empty?
+			# Default to the currently configured site-pages keyword so changing it
+			# 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
@@ -209,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)
@@ -344,7 +358,7 @@ class Normaliser
 		def normalise_collection_targets(raw_collection, split_delimiter:, keywords:)
 			default_targets = Utils.deep_copy(DEFAULTS['collection'])
 			entries = Utils.delimited_array(raw_collection, delimiter: split_delimiter)
-			entries = Utils.deep_copy(default_targets) if entries.empty?
+			return default_targets if entries.empty?
 
 			normalised = entries.map do |entry|
 				normalise_collection_target_entry(entry, keywords)
@@ -363,21 +377,12 @@ class Normaliser
 			entry = raw_entry.to_s.strip
 			return '' if entry.empty?
 
-			keyword_map = {
-				'pages' => keywords['pages'],
-				'self' => keywords['self'],
-				'shadow' => keywords['shadow'],
-				'clone' => keywords['clone']
-			}
-
-			keyword_map.each do |canonical, keyword|
+			COLLECTION_TARGET_BY_KEY.each do |key, internal_target|
+				keyword = keywords[key]
 				next if keyword.to_s.empty?
-				return canonical if entry == keyword
+				return internal_target if entry == keyword
 			end
 
-			canonical = entry.downcase
-			return canonical if %w[pages self shadow clone].include?(canonical)
-
 			entry
 		end
 
@@ -388,7 +393,7 @@ class Normaliser
 		def build_page_templates(page2_title, page2_permalink)
 			{
 				'page1' => {
-					'title' => ':title',
+					'title' => '{{ title }}',
 					'permalink' => ''
 				},
 				'page2' => {
@@ -460,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?
@@ -472,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:)
@@ -505,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
@@ -577,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/generators/pagination_generator.rb

@@ -149,7 +149,7 @@ class PaginationGenerator < Jekyll::Generator
 	# Converts a generated-template destination location into readable text.
 	def generated_template_location_label(collection_targets)
 		targets = Utils.arrayify(collection_targets).map(&:to_s).map(&:strip).reject(&:empty?)
-		targets = ['pages'] if targets.empty?
+		targets = [Config::COLLECTION_TARGET_PAGES] if targets.empty?
 		return target_label(targets.first) if targets.length == 1
 
 		"page1=#{target_label(targets.first)} page2+=#{target_label(targets[1])}"
@@ -157,7 +157,7 @@ class PaginationGenerator < Jekyll::Generator
 
 	# Converts one collection target token to a readable log label.
 	def target_label(target)
-		return 'pages (site root)' if target == 'pages'
+		return 'pages (site root)' if target == Config::COLLECTION_TARGET_PAGES
 
 		"collection '#{target}'"
 	end

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

@@ -28,7 +28,7 @@ class Model
 		@nested_separator = site_config.dig('syntax', 'separator')
 		@split_delimiter = site_config.dig('syntax', 'split')
 		@equivalents = site_config['equivalents']
-		@item_keyword = site_config.dig('keywords', 'items') || 'items'
+		@item_keyword = site_config.dig('keywords', 'items') || Config::KEYWORD_DEFAULTS.fetch('items')
 		@generated_index_sets = {}
 		@clone_collection_cache = {}
 		@template_search_reports = []
@@ -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.
@@ -490,13 +508,13 @@ class Model
 		[Utils.item_collection_label(item).to_s, Utils.relative_item_path(item)]
 	end
 
-	# Resolves one parsed search entry (`pages`, collection label, etc).
+	# Resolves one parsed search entry (a private source type or collection label).
 	def resolve_entry(entry)
 		type = entry['type']
 		paths = entry['paths']
 		source_items = source_items_for_entry_type(type)
 		if source_items.nil?
-			log("Search entry type='#{type}' did not match pages/all/everything or a known collection; resolved 0 items.", 'warn')
+			log("Search entry type='#{type}' did not match a configured search keyword or known collection; resolved 0 items.", 'warn')
 			return []
 		end
 
@@ -512,11 +530,11 @@ class Model
 	# Resolves source items for one parsed search entry type.
 	def source_items_for_entry_type(type)
 		case type
-		when 'pages'
+		when Query::Parser::SEARCH_TYPE_PAGES
 			@item_resolution_pages || @site.pages
-		when 'all'
+		when Query::Parser::SEARCH_TYPE_ALL
 			all_collection_documents
-		when 'everything'
+		when Query::Parser::SEARCH_TYPE_EVERYTHING
 			(@item_resolution_pages || @site.pages) + all_collection_documents
 		else
 			return @item_resolution_documents_by_collection[type] if @item_resolution_documents_by_collection&.key?(type)

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.