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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 036fbbfba18f61ae73a069e4330fce833a1cb7549704c9bf396961ddd262569f
-  data.tar.gz: 061d674f1bfd29de53bb79bc5a64feb8076a80af38f59be877f3cc77443173ff
+  metadata.gz: 4167a9c3e76eb08e45275f31be52227e30a6b6d453f1bceef0c901097d4250f7
+  data.tar.gz: e8e96586a43ff094865264446fc5389555438c74e87dbeb38f5c0c818b2ed47e
 SHA512:
-  metadata.gz: e6561b1d072672dabdbace597b3b7d310a3f357f7d9b05a1f6815d7b29e634029faf7828ca8105edf6cc41fd1cab276e215de8343358c53e42b482e005f64235
-  data.tar.gz: 259bd8d452c747203d316a977de290141b11bc1061a39386e0bac81733f1ace2b08ef0b9c1d8092212e232544bb6f8f758e2e49327b6779f54116e555213a7d4
+  metadata.gz: 457fc67c2920f51aac38003b395720365df59f5786a9fb71f1d34c6d68d5a279abb32f10608b3d4c2c66b93934f8108e26175165795bb4a253c43898eb89d12d
+  data.tar.gz: a44bb5a0591d319502f0f574d5fa0493a4636477e7a8301ba9a9c5fc712b74f1564b169617b15c950512f52f29d2a23d3b6207c86b8d09cddbd182f81e4fdca3

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

@@ -27,6 +27,20 @@ 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
+
 	DEFAULTS = {
 		'enabled' => true,
 		'compatibility' => nil,
@@ -41,7 +55,7 @@ module Config
 			['category', 'categories']
 		],
 		'items' => nil,
-		'collection' => ['self', 'shadow'],
+		'collection' => [COLLECTION_TARGET_SELF, COLLECTION_TARGET_SHADOW],
 		'filters' => nil,
 		'sort' => 'date desc',
 		'per_page' => 10,
@@ -58,7 +72,7 @@ module Config
 			'lowercase' => true
 		},
 		'templates' => {
-			'location' => 'pages',
+			'location' => nil,
 			'generate' => []
 		}
 	}.freeze
@@ -95,7 +109,6 @@ module Config
 			},
 			'items' => 'posts',
 			'templates' => {
-				'location' => 'pages',
 				'generate' => []
 			}
 		}

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

@@ -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')
 											))

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,13 +189,15 @@ 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) }
 									elsif source['generate'].is_a?(Hash)
@@ -344,7 +347,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 +366,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
 

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 = []
@@ -490,13 +490,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 +512,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/pagination_pipeline.rb

@@ -253,9 +253,9 @@ class Model
 		target_collection = collection_target_for_page(template, target_mode)
 
 		case target_mode
-		when 'pages'
+		when Config::COLLECTION_TARGET_PAGES
 			Pages::Page.new(template, current_page, total_pages, index_file)
-		when 'shadow'
+		when Config::COLLECTION_TARGET_SHADOW
 			Pages::ShadowPage.new(
 				template,
 				current_page,
@@ -281,7 +281,7 @@ class Model
 	# Resolves one normalised collection mode for a generated page number.
 	def collection_target_mode_for_page(template, config, current_page)
 		targets = Utils.arrayify(config['collection']).map(&:to_s).map(&:strip).reject(&:empty?)
-		targets = ['self', 'shadow'] if targets.empty?
+		targets = [Config::COLLECTION_TARGET_SELF, Config::COLLECTION_TARGET_SHADOW] if targets.empty?
 		target = current_page == 1 ? targets.first : targets.last
 
 		normalise_collection_target_for_template(template, target)
@@ -290,11 +290,11 @@ class Model
 	# Resolves one collection object for collection-targeted modes.
 	def collection_target_for_page(template, target_mode)
 		case target_mode
-		when 'self'
+		when Config::COLLECTION_TARGET_SELF
 			return template.collection if collection_template?(template)
-		when 'clone'
+		when Config::COLLECTION_TARGET_CLONE
 			return clone_collection_for(template.collection) if collection_template?(template)
-		when 'pages', 'shadow'
+		when Config::COLLECTION_TARGET_PAGES, Config::COLLECTION_TARGET_SHADOW
 			return nil
 		end
 
@@ -304,13 +304,13 @@ class Model
 	# Converts abstract target modes to executable runtime modes.
 	def normalise_collection_target_for_template(template, target_mode)
 		value = target_mode.to_s.strip
-		value = 'pages' if value.empty?
-		return value unless %w[self shadow clone].include?(value)
-		return 'pages' unless collection_template?(template)
-		return value if value == 'self'
-		return value if value == 'clone'
+		value = Config::COLLECTION_TARGET_PAGES if value.empty?
+		return value unless [Config::COLLECTION_TARGET_SELF, Config::COLLECTION_TARGET_SHADOW, Config::COLLECTION_TARGET_CLONE].include?(value)
+		return Config::COLLECTION_TARGET_PAGES unless collection_template?(template)
+		return value if value == Config::COLLECTION_TARGET_SELF
+		return value if value == Config::COLLECTION_TARGET_CLONE
 
-		'shadow'
+		Config::COLLECTION_TARGET_SHADOW
 	end
 
 	# Returns true when a template is a collection document.
@@ -365,7 +365,8 @@ class Model
 			@site.config['defaults'] << clone_entry
 		end
 
-		@site.frontmatter_defaults.reset if @site.respond_to?(:frontmatter_defaults)
+		frontmatter_defaults = @site.frontmatter_defaults if @site.respond_to?(:frontmatter_defaults)
+		frontmatter_defaults.reset if frontmatter_defaults.respond_to?(:reset)
 	end
 
 	# Attaches a compact neighbourhood of page links around each generated
@@ -437,7 +438,7 @@ class Model
 			@generated_index_sets[set_id] ||= []
 			@generated_index_sets[set_id] << {
 				'pages' => generated_pages,
-				'count' => generated_pages.first.pager.total_items,
+				'count' => generated_pages.first.pager.total_item_count,
 				'start' => metadata['start'],
 				'end' => metadata['end'],
 				'order' => metadata['order'].to_i,

data/lib/jekyll-paginate-v3/pagination/pages/document.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'digest'
-
 module Jekyll
 module Plugins
 module PaginateV3
@@ -22,7 +20,8 @@ class Document < Jekyll::Document
 	def initialize(template_item, current_page, total_pages, _index_filename, collection:)
 		target_collection = collection
 		source_path = template_path(template_item)
-		virtual_path = build_virtual_path(template_item.site, target_collection, source_path, current_page)
+		extension = template_extname(template_item)
+		virtual_path = build_virtual_path(template_item, target_collection, source_path, current_page, extension)
 
 		initialise_document(template_item.site, target_collection, virtual_path)
 
@@ -32,7 +31,7 @@ class Document < Jekyll::Document
 			'curr_page' => current_page,
 			'total_pages' => total_pages
 		}
-		@extname = template_extname(template_item)
+		@extname = extension
 		self.data['path'] = source_path if current_page == 1 && !source_path.empty?
 
 		trigger_hooks(:post_init)
@@ -41,10 +40,22 @@ class Document < Jekyll::Document
 	private
 
 	# Builds a deterministic synthetic source path inside destination collection.
-	def build_virtual_path(site, collection, source_path, current_page)
-		signature = [source_path, collection.label, current_page].join(':')
-		filename = "_paginate_v3_#{Digest::MD5.hexdigest(signature)}.md"
-		File.join(site.source, collection.relative_directory, filename)
+	def build_virtual_path(template_item, collection, source_path, current_page, extension)
+		Utils.build_synthetic_source_path(
+			site: template_item.site,
+			collection: collection,
+			extension: extension,
+			source_path: source_path,
+			role: 'page',
+			page_number: current_page,
+			signature: {
+				'source_path' => source_path,
+				'collection' => collection.label.to_s,
+				'page_number' => current_page,
+				'template_data' => Utils.safe_hash(template_item.data),
+				'template_content' => template_item.content.to_s
+			}
+		)
 	end
 
 	# Resolves source path for compatibility metadata.
@@ -77,7 +88,10 @@ class Document < Jekyll::Document
 		end
 
 		data.default_proc = proc do |_, key|
-			site.frontmatter_defaults.find(relative_path, type, key)
+			# Jekyll 3 does not expose `type` as a public Document method, while
+			# Jekyll 4 does. The internal type is set immediately above and works
+			# consistently with both supported Jekyll versions.
+			site.frontmatter_defaults.find(relative_path, @type, key)
 		end
 	end
 end

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

@@ -13,15 +13,15 @@ module Pagination
 # Used by Pagination::Model for every generated page/document.
 class Paginator < ::Liquid::Drop
 
-	attr_reader :per_page, :items, :total_items, :total_indexes, :current, :next, :previous, :first, :last, :trail, :groups
+	attr_reader :per_page, :total_item_count, :total_indexes, :current, :next, :previous, :first, :last, :trail, :groups
 
 	def initialize(per_page:, items:, current_page:, total_pages:, item_keyword:, compatibility: nil, page_windows: nil)
 		@per_page_pattern = Utils.normalise_per_page_pattern(per_page)
 		@current_index_number = current_page.to_i
 		@item_keyword = normalise_item_keyword(item_keyword)
 		@compatibility_mode = normalise_compatibility_mode(compatibility)
-		@total_items = items.size
-		@page_windows = normalise_page_windows(page_windows, @total_items)
+		@total_item_count = items.size
+		@page_windows = normalise_page_windows(page_windows, @total_item_count)
 		requested_total_indexes = [total_pages.to_i, 1].max
 
 		if @current_index_number > requested_total_indexes
@@ -35,7 +35,7 @@ class Paginator < ::Liquid::Drop
 
 		current_window = window_for_page_number(@current_index_number)
 		@per_page = current_window['page_size']
-		@items = items[current_window['offset_start']...current_window['offset_end']] || []
+		@page_items = items[current_window['offset_start']...current_window['offset_end']] || []
 		@trail = nil
 		@groups = []
 
@@ -184,11 +184,12 @@ class Paginator < ::Liquid::Drop
 	#
 	# Liquid rendering uses this Drop instance directly.
 	def to_h
-		payload = canonical_payload_hash
-		payload[@item_keyword] = items
-		payload["total_#{@item_keyword}"] = total_items
+		payload = standard_payload_hash
+		payload[@item_keyword] = @page_items
+		payload["total_#{@item_keyword}"] = @total_item_count
 
 		if compatibility_mode?
+			add_compatibility_item_keys!(payload)
 			payload.merge!(
 				'per_page' => per_page,
 				'page' => page,
@@ -212,19 +213,28 @@ class Paginator < ::Liquid::Drop
 	# Handles dynamic alias keys that are not explicit methods.
 	def liquid_method_missing(method_name)
 		method_key = method_name.to_s
-		return items if method_key == @item_keyword
-		return total_items if method_key == "total_#{@item_keyword}"
+		return @page_items if method_key == @item_keyword
+		return @total_item_count if method_key == "total_#{@item_keyword}"
 
 		super
 	end
 
 	private
 
-	# Canonical v3 paginator payload hash.
-	def canonical_payload_hash
+	# Restores canonical item keys only for explicitly selected v1/v2
+	# compatibility profiles, whose historical paginator APIs require them.
+	def add_compatibility_item_keys!(payload)
+		canonical_keyword = Config::KEYWORD_DEFAULTS.fetch('items')
+		return if @item_keyword == canonical_keyword
+
+		payload[canonical_keyword] = @page_items
+		payload["total_#{canonical_keyword}"] = @total_item_count
+	end
+
+	# Builds the paginator payload shared by every configured item keyword.
+	# Item keys themselves are added by `to_h` using the active keyword only.
+	def standard_payload_hash
 		{
-			'items' => items,
-			'total_items' => total_items,
 			'total_indexes' => total_indexes,
 			'current' => current,
 			'next' => self.next,
@@ -275,8 +285,8 @@ class Paginator < ::Liquid::Drop
 			'num' => page_number.to_i,
 			'page_size' => fallback_size,
 			'count' => 0,
-			'offset_start' => total_items,
-			'offset_end' => total_items,
+			'offset_start' => total_item_count,
+			'offset_end' => total_item_count,
 			'start' => nil,
 			'end' => nil
 		}
@@ -310,10 +320,10 @@ class Paginator < ::Liquid::Drop
 		@page_windows_by_number.values
 	end
 
-	# Normalises item alias keyword; falls back to canonical `items`.
+	# Normalises the configured item keyword for direct Paginator callers.
 	def normalise_item_keyword(raw_keyword)
 		keyword = raw_keyword.to_s.strip
-		keyword.empty? ? 'items' : keyword
+		keyword.empty? ? Config::KEYWORD_DEFAULTS.fetch('items') : keyword
 	end
 
 	# Normalises compatibility mode to one supported legacy profile.

data/lib/jekyll-paginate-v3/query/parser.rb

@@ -17,7 +17,16 @@ module Query
 # sources into concrete site items.
 class Parser
 
-	CANONICAL_TYPES = %w[pages all everything].freeze
+	# Internal search-source identifiers. Keeping them distinct from collection
+	# labels means changing a keyword genuinely releases its former label.
+	SEARCH_TYPE_PAGES = '__paginate_v3_search_pages__'.freeze
+	SEARCH_TYPE_ALL = '__paginate_v3_search_all__'.freeze
+	SEARCH_TYPE_EVERYTHING = '__paginate_v3_search_everything__'.freeze
+	SEARCH_TYPE_BY_KEY = {
+		'pages' => SEARCH_TYPE_PAGES,
+		'all' => SEARCH_TYPE_ALL,
+		'everything' => SEARCH_TYPE_EVERYTHING
+	}.freeze
 
 	# Parses a search definition into an array of normalised entries.
 	#
@@ -112,13 +121,13 @@ class Parser
 			end
 		end
 
-		# Maps configurable keyword aliases (`pages`, `all`, `everything`)
-		# to their canonical internal type.
+		# Maps only configured keyword aliases to internal search-source types.
+		# The former keyword remains an ordinary collection label after a rename.
 		def canonical_type(type, keywords)
 			string_type = type.to_s.strip
-			return 'pages' if string_type == 'pages' || string_type == keywords['pages']
-			return 'all' if string_type == 'all' || string_type == keywords['all']
-			return 'everything' if string_type == 'everything' || string_type == keywords['everything']
+			SEARCH_TYPE_BY_KEY.each do |key, internal_type|
+				return internal_type if string_type == keywords[key]
+			end
 
 			string_type
 		end

data/lib/jekyll-paginate-v3/templates/builder/core.rb

@@ -100,7 +100,7 @@ class Builder
 		pagination_config['enabled'] = true
 
 		first_target = definition['template_collection'].first
-		if first_target == 'pages'
+		if first_target == Config::COLLECTION_TARGET_PAGES
 			Templates::PageTemplate.new(
 				site: @site,
 				pagination_config: pagination_config,

data/lib/jekyll-paginate-v3/templates/builder/definition_normalisation.rb

@@ -45,32 +45,29 @@ class Builder
 		entries
 	end
 
-	# Normalises one collection target and coerces template-relative keywords.
+	# Normalises one generated-template collection target. Generated templates
+	# have no source collection, so all collection-mode keywords become pages.
 	def normalise_collection_entry(raw_entry)
 		entry = raw_entry.to_s.strip
 		return '' if entry.empty?
 
-		pages_keyword = @site_config.dig('keywords', 'pages').to_s
-		self_keyword = @site_config.dig('keywords', 'self').to_s
-		shadow_keyword = @site_config.dig('keywords', 'shadow').to_s
-		clone_keyword = @site_config.dig('keywords', 'clone').to_s
+		return Config::COLLECTION_TARGET_PAGES if Config::COLLECTION_TARGET_BY_KEY.value?(entry)
 
-		return 'pages' if entry == pages_keyword || entry.casecmp('pages').zero?
-		return 'pages' if entry == self_keyword || entry.casecmp('self').zero?
-		return 'pages' if entry == shadow_keyword || entry.casecmp('shadow').zero?
-		return 'pages' if entry == clone_keyword || entry.casecmp('clone').zero?
+		Config::COLLECTION_TARGET_BY_KEY.each do |key, _internal_target|
+			return Config::COLLECTION_TARGET_PAGES if entry == @site_config.dig('keywords', key).to_s
+		end
 
 		entry
 	end
 
 	# Resolves default generated-template collection targets from site defaults.
 	#
-	# `self`, `shadow`, and `clone` are template-relative modes and therefore
-	# become `pages` during template generation.
+	# Template-relative modes become the internal pages target during template
+	# generation because a generated template has no source collection.
 	def default_generation_collection
 		raw_collection = @site_config['collection']
 		entries = Utils.arrayify(raw_collection).map { |entry| entry.to_s.strip }.reject(&:empty?)
-		entries = ['pages'] if entries.empty?
+		entries = [Config::COLLECTION_TARGET_PAGES] if entries.empty?
 		if entries.length > 2
 			raise ArgumentError, 'pagination.collection may contain at most two values.'
 		end

data/lib/jekyll-paginate-v3/templates/builder/token_metadata.rb

@@ -194,9 +194,9 @@ class Builder
 		labels = []
 		Query::Parser.parse(raw_items, @site_config['keywords'], split_delimiter: @split_delimiter).each do |entry|
 			case entry['type']
-			when 'all', 'everything'
+			when Query::Parser::SEARCH_TYPE_ALL, Query::Parser::SEARCH_TYPE_EVERYTHING
 				labels.concat(@site.collections.keys)
-			when 'pages'
+			when Query::Parser::SEARCH_TYPE_PAGES
 				# pages do not map to collections
 			else
 				labels << entry['type'] if @site.collections.key?(entry['type'])

data/lib/jekyll-paginate-v3/templates/document_template.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'digest'
-
 module Jekyll
 module Plugins
 module PaginateV3
@@ -18,7 +16,7 @@ class DocumentTemplate < Jekyll::Document
 	# Creates an in-memory collection document seeded from frontmatter and
 	# content supplied by generate config.
 	def initialize(site:, collection:, pagination_config:, frontmatter:, content:, generated_metadata:)
-		virtual_path = build_virtual_path(site, collection, pagination_config, frontmatter)
+		virtual_path = build_virtual_path(site, collection, pagination_config, frontmatter, content)
 		generated_metadata_hash = Utils.safe_hash(generated_metadata)
 
 		initialise_document(site, collection, virtual_path)
@@ -38,10 +36,21 @@ class DocumentTemplate < Jekyll::Document
 
 	# Builds a deterministic synthetic source path inside destination
 	# collection.
-	def build_virtual_path(site, collection, pagination_config, frontmatter)
-		signature = [collection.label, pagination_config, frontmatter].inspect
-		filename = "_paginate_v3_generated_#{Digest::MD5.hexdigest(signature)}.md"
-		File.join(site.source, collection.relative_directory, filename)
+	def build_virtual_path(site, collection, pagination_config, frontmatter, content)
+		Utils.build_synthetic_source_path(
+			site: site,
+			collection: collection,
+			extension: '.md',
+			source_stem: Utils.derive_synthetic_source_stem_from_frontmatter(frontmatter, fallback: collection.label),
+			role: 'template',
+			signature: {
+				'collection' => collection.label.to_s,
+				'pagination' => Utils.safe_hash(pagination_config),
+				'frontmatter' => Utils.safe_hash(frontmatter),
+				'content' => content.to_s,
+				'content_type' => 'document-template'
+			}
+		)
 	end
 
 	# Adds legacy-friendly fields only when v2 compatibility is active.

data/lib/jekyll-paginate-v3/templates/page_template.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'digest'
-
 module Jekyll
 module Plugins
 module PaginateV3
@@ -20,7 +18,7 @@ class PageTemplate < Jekyll::Page
 		@dir = '/'
 		@name = 'index.html'
 		@url = '/'
-		@path = build_virtual_path(site, pagination_config, frontmatter)
+		@path = build_virtual_path(site, pagination_config, frontmatter, content)
 
 		process(@name)
 
@@ -42,9 +40,19 @@ class PageTemplate < Jekyll::Page
 	private
 
 	# Builds a deterministic virtual source path for this synthetic page.
-	def build_virtual_path(site, pagination_config, frontmatter)
-		signature = [pagination_config, frontmatter].inspect
-		File.join(site.source, "_paginate_v3_generated_#{Digest::MD5.hexdigest(signature)}.md")
+	def build_virtual_path(site, pagination_config, frontmatter, content)
+		Utils.build_synthetic_source_path(
+			site: site,
+			extension: '.md',
+			source_stem: Utils.derive_synthetic_source_stem_from_frontmatter(frontmatter, fallback: 'generated-template'),
+			role: 'template',
+			signature: {
+				'pagination' => Utils.safe_hash(pagination_config),
+				'frontmatter' => Utils.safe_hash(frontmatter),
+				'content' => content.to_s,
+				'content_type' => 'page-template'
+			}
+		)
 	end
 
 	# Adds legacy-friendly fields only when v2 compatibility is active.

data/lib/jekyll-paginate-v3/utils/paths.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'digest'
+
 module Jekyll
 module Plugins
 module PaginateV3
@@ -49,6 +51,99 @@ module Utils
 
 		url
 	end
+
+	# Builds one deterministic synthetic source path for in-memory pages
+	# and documents. Filenames remain readable for debugging while a hash
+	# suffix preserves practical uniqueness across templates and variants.
+	def self.build_synthetic_source_path(site:, extension:, signature:, collection: nil, source_path: nil, source_stem: nil, role:, page_number: nil)
+		directory = collection.nil? ? site.source : File.join(site.source, collection.relative_directory)
+		File.join(
+			directory,
+			build_synthetic_filename(
+				extension: extension,
+				signature: signature,
+				source_path: source_path,
+				source_stem: source_stem,
+				role: role,
+				page_number: page_number
+			)
+		)
+	end
+
+	# Builds one readable synthetic filename from source identity plus a
+	# deterministic safety suffix.
+	def self.build_synthetic_filename(extension:, signature:, source_path: nil, source_stem: nil, role:, page_number: nil)
+		stem = derive_synthetic_source_stem(source_path: source_path, source_stem: source_stem, fallback: role)
+		filename_segments = [stem, role.to_s.strip]
+		filename_segments << page_number.to_i.to_s unless page_number.nil?
+		filename_segments << Digest::MD5.hexdigest(canonical_signature(signature).inspect)
+		"#{filename_segments.reject(&:empty?).join('-')}#{ensure_leading_dot(extension)}"
+	end
+
+	# Derives one human-readable synthetic stem from an original source
+	# path or fallback label.
+	def self.derive_synthetic_source_stem(source_path: nil, source_stem: nil, fallback: 'generated')
+		candidate = extract_source_filename_stem(source_path)
+		candidate = source_stem.to_s if candidate.empty?
+		candidate = fallback.to_s if candidate.to_s.strip.empty?
+		sanitise_filename_component(candidate, fallback: fallback)
+	end
+
+	# Derives one readable stem from frontmatter when no real source path
+	# exists, preferring permalink and then title.
+	def self.derive_synthetic_source_stem_from_frontmatter(frontmatter, fallback: 'generated')
+		frontmatter_hash = safe_hash(frontmatter)
+		permalink_stem = extract_permalink_stem(frontmatter_hash['permalink'])
+		return derive_synthetic_source_stem(source_stem: permalink_stem, fallback: fallback) unless permalink_stem.empty?
+
+		derive_synthetic_source_stem(source_stem: frontmatter_hash['title'], fallback: fallback)
+	end
+
+	# Extracts one source-style stem from a real path-like value.
+	def self.extract_source_filename_stem(source_path)
+		path = source_path.to_s
+		return '' if path.strip.empty?
+
+		File.basename(path, File.extname(path))
+	end
+
+	# Extracts one final path segment from a permalink-like value.
+	def self.extract_permalink_stem(permalink)
+		path = permalink.to_s.strip
+		return '' if path.empty?
+
+		segments = path.split('/').reject(&:empty?)
+		return '' if segments.empty?
+
+		File.basename(segments.last, File.extname(segments.last))
+	end
+
+	# Sanitises one filename component while preserving source readability
+	# where the original stem is already filesystem-safe.
+	def self.sanitise_filename_component(value, fallback: 'generated')
+		component = value.to_s.strip
+		component = component.gsub(%r{[\\/]}, '-')
+		component = component.gsub(/[<>:"|?*\x00-\x1f]/, '-')
+		component = component.gsub(/^-+/, '')
+		component = component.gsub(/[. ]+$/, '')
+		component = fallback.to_s if component.empty?
+		component
+	end
+
+	# Canonicalises nested signature data so hashes with identical meaning
+	# yield the same suffix regardless of insertion order.
+	def self.canonical_signature(value)
+		case value
+		when Hash
+			value.each_with_object({}) do |(key, nested_value), canonical|
+				canonical[key.to_s] = canonical_signature(nested_value)
+			end.sort_by { |key, _| key }.to_h
+		when Array
+			value.map { |entry| canonical_signature(entry) }
+		else
+			value
+		end
+	end
 end
 
 end

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

@@ -4,7 +4,7 @@ module Jekyll
 module Plugins
 
 module PaginateV3
-	VERSION = '0.1.0.alpha.2'
+	VERSION = '0.1.0.alpha.3'
 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.2
+  version: 0.1.0.alpha.3
 platform: ruby
 authors:
 - Convincible
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -44,6 +44,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.1.0.alpha
+- !ruby/object:Gem::Dependency
+  name: kramdown-parser-gfm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement