jekyll-paginate vs jekyll-paginate-v2 for multi-collection sites

Answer the core question first

If your site requires independent paginated lists for more than one collection (e.g., a blog and a product catalog), use jekyll‑paginate‑v2. The core jekyll‑paginate plugin can only paginate site.posts on a single page, so it cannot meet that requirement.

Why the difference matters

• Core plugin – bundled with Jekyll, no extra gems, minimal _config.yml (just paginate: 5 and paginate_path), but limited to one pagination context.
• jekyll‑paginate‑v2 – community gem that introduces a pagination: block where you declare one or more generators, each targeting a distinct collection, with its own per_page, permalink, and optional sort settings.

When the core plugin is still enough

If you only need a single paginated list (for example, a simple blog on index.html), the core plugin’s zero‑dependency, zero‑configuration advantage outweighs any feature set of v2. It also stays in sync with Jekyll releases and works out of the box on GitHub Pages.

Setting up jekyll‑paginate‑v2 for two collections

1. Add the gem to your Gemfile and _config.yml:

   gem 'jekyll-paginate-v2'
   

2. Include it in the plugins list in _config.yml:

   plugins:
     - jekyll-paginate-v2
   

3. Define two generators:

   pagination:
     generators:
       - name: blog
         collection: posts
         per_page: 10
         permalink: '/blog/page:num/'
       - name: shop
         collection: products
         per_page: 12
         permalink: '/shop/page:num/'
   

4. In templates, reference the paginator under the generator name, e.g.:

   {% for post in paginator.blog.posts %}
     {{ post.title }}
   {% endfor %}
   

5. Run bundle exec jekyll build locally. Note that GitHub Pages does not support this gem, so you must deploy the built _site folder or use a CI pipeline that runs the build.

Potential pitfalls and how to mitigate them

• Configuration errors (duplicate generator names, missing collections) can silently break pagination; validate the _config.yml syntax with jekyll build --config _config.yml and check the console for errors.
• Changing the paginator variable name in templates is required when moving from core to v2; otherwise the old paginator.posts will be empty.
• Because v2 is community‑maintained, it may lag behind the latest Jekyll releases. Check the gem’s GitHub repo for recent commits before adopting it in production.

Ask for missing diagnostic detail

To confirm whether v2 is truly necessary for your site, could you tell me how many collections you need to paginate independently? If it’s only one, the core plugin remains the simpler choice.