Implementing Built‑in Pagination in Eleventy for Archive Pages

Desired outcome

Generate a series of static archive pages (e.g., /blog/page-1/, /blog/page-2/) from a collection using Eleventy’s declarative pagination, without writing custom Node build scripts.

Necessary prerequisites

• An Eleventy project (v1.x or later) initialized with npm init -y and npm install @11ty/eleventy --save-dev.
• Node.js >=14 installed.
• At least one template engine configured (Nunjucks, Liquid, or 11ty.js).
• A collection or data array containing more items than the page size you intend to use (e.g., a collections.posts array with >5 items).

Focused procedure

1. Add pagination front matter to the template that will become the archive index (e.g., blog.njk).

---
pagination:
  data: collections.posts
  size: 5
  alias: posts
permalink: /blog/page-{pagination.pageNumber}/
---

1. Render the paginated items inside the template body using the alias you defined (or the default pagination.items).

{% for post in posts %}
  
{{ post.data.title }}
  {{ post.templateContent | safe }}
{% endfor %}

{% if pagination.pages > 1 %}
  
    {% if pagination.pageNumber > 1 %}
      Previous
    {% endif %}
    Page {{ pagination.pageNumber }} of {{ pagination.pages }}
    {% if pagination.pageNumber < pagination.pages %}
      Next
    {% endif %}
  
{% endif %}

1. Start a local development server to preview the output.

# Run from the project root
npx @11ty/eleventy --serve

Expected checks

• After the build completes, open http://localhost:8080/ and navigate to /blog/page-1/, /blog/page-2/, etc. Verify that the URLs match the pattern defined in permalink.
• Inspect the generated HTML files in the output directory (default _site). Count the files; the number should equal Math.ceil(totalItems / size).
• Open any page and confirm that exactly size items (e.g., 5) are listed in the loop.
• Optionally add a temporary debug snippet to verify pagination values:

<p>pageNumber: {{ pagination.pageNumber }}, pages: {{ pagination.pages }}, items: {{ posts.length }}</p>

Recovery options

• No pages generated:
  Ensure the data source (collections.posts) is not empty. Check that size is a positive integer (>0). If size is omitted or zero, Eleventy may paginate all items on a single page or fail, depending on the version.
• Unexpected URLs:
  Verify the permalink string uses the correct pagination variable ({pagination.pageNumber}) and that no conflicting permalink is set elsewhere in the template or in a directory data file.
• Very large collections:
  Reduce the size value to lower memory usage, or increase Node memory with NODE_OPTIONS=--max-old-space-size=4096 npx @11ty/eleventy. Monitor build time; if it becomes prohibitive, consider splitting the collection into multiple data files.
• Version‑specific behavior:
  Run npx @11ty/eleventy --version and consult the pagination documentation for that exact release, as front‑matter keys (pagination.data, pagination.size, pagination.alias) have changed between major versions.

Practical verification

1. Check the installed Eleventy version:

npx @11ty/eleventy --version

1. Run a production build and inspect the output directory:

npx @11ty/eleventy
ls -1 _site/blog/ | wc -l   # should match pagination.pages

1. Add the debug snippet from step 4 of the focused procedure, rebuild, and confirm the numbers appear as expected.

If the checks pass, the pagination is correctly configured and you can proceed to style the archive pages.