Pagination URL rules and examples
Base behavior
- Parent permalink with placeholders: If a paginated page’s permalink includes
{{page}}
or{{pageNumber}}
, page 1 uses the canonical base (placeholders removed) and pages 2+ replace the placeholders with the page number. - Parent permalink without placeholders: Page 1 uses the parent permalink; pages 2+ default to
page/<n>/
under the same base path. - No parent permalink: Uses
/<fileSlug>/
as the base. Pages 2+ default to/<fileSlug>/page/<n>/
. - Trailing slash → file: If a permalink ends with
/
, it maps toindex.html
under that path. If it includes a filename with an extension, that file is written directly.
Navigation
first
and page 1 hrefs point to the canonical first URL (base permalink without placeholders, with a trailing slash when using directory-style permalinks).previous
from page 2 points to the canonical first URL.
Size-specific notes
- Multi-item pages (
size > 1
): follow the rules above for base and numbered pages. - Single-item pages (
size == 1
with alias): the alias placeholder (e.g.,{{tag}}
) is replaced with each item; page numbering isn’t used.
Examples
-
Placeholder style (multi-item)
Front matter:
permalink: /blog/page/{{page}}/ pagination: data: collections.post size: 5
Output:
- Page 1:
/blog/index.html
(href/blog/
) - Page 2:
/blog/page/2/index.html
(href/blog/page/2/
)
- Page 1:
-
No placeholder (multi-item)
Front matter:
permalink: /articles/ pagination: data: collections.post size: 5
Output:
- Page 1:
/articles/index.html
(href/articles/
) - Page 2:
/articles/page/2/index.html
(href/articles/page/2/
)
- Page 1:
-
No permalink provided (multi-item)
Front matter:
pagination: data: collections.post size: 5
Output base path is
/<fileSlug>/
.- Page 1:
/<fileSlug>/index.html
- Page 2:
/<fileSlug>/page/2/index.html
- Page 1:
-
Single-item with alias
Front matter:
permalink: /tag/{{tag}}.html pagination: data: collections.tags alias: tag size: 1
Output: One file per tag such as
/tag/cfml.html
,/tag/boxlang.html
, etc.