Which pagination approach should I use: front‑matter pagination or a custom collection in .eleventy.js?

Direct answer

For a standard blog that needs clean URLs and predictable template variables, use Eleventy’s built-in front-matter pagination with an alias and a permalink function. A custom collection in .eleventy.js does not replace pagination; it only supplies data and adds indirection.

What is confirmed

• Template variable names: Front-matter pagination’s alias key renames the items array directly in the template. For example, alias: posts exposes a posts variable. A custom collection does not rename variables; the template still references the collection name or a template-level alias, so front matter usually yields clearer names.
• Permalink control: Front-matter pagination accepts a string or a function for permalink, so patterns like /posts/page/{{ pagination.pageNumber }}/ or a JavaScript function returning /posts/page/2/ are native. A custom collection alone does not define output URLs; you still need a template with a permalink, so it adds a layer rather than capability.

Likely explanation: build time and plugins

Build-time differences are small for typical blogs. Front-matter pagination is core Eleventy behavior, so plugins and themes assume its data shape. Custom collections run JavaScript during configuration and can surprise plugins that expect standard pagination objects, creating compatibility risk even if raw speed is similar. Heavy computation inside addCollection also runs on every build.

Steps for this case

1. Use a template with pagination in front matter:

   ---
   pagination:
     data: collections.post
     size: 10
     alias: posts
   permalink: /posts/page/{{ pagination.pageNumber }}/
   ---

2. If you need a function instead of a string, pass a permalink function that receives the pagination object and returns the desired path. Test first-page numbering, zero-based versus one-based page numbers, and trailing-slash consistency on your host.
3. If you still need a custom collection for data shaping, keep it in .eleventy.js and feed it into front-matter pagination via data: collections.myCustomSet.

Version assumption and verification

This reflects stable Eleventy 1.x, 2.x, and 3.x pagination semantics. Because permalink template syntax and pagination object details have changed across major versions, verify against your installed version before relying on edge cases. Build twice with the same content and inspect the output tree for /posts/page/2/ and the posts variable to confirm behavior.

If your page set requires logic that front matter cannot express—such as conditional page sizes or cross-collection merging—share that logic, because that is the only scenario where a custom collection plus a paginated template is justified.