Setting Up Jekyll Pagination for Blog Posts

Desired outcome

Enable pagination so that blog posts are split across multiple pages (e.g., index.html, page2/index.html, …) with navigation links that work correctly.

Prerequisites

• Jekyll 4.x or later installed (the pagination feature is provided by the jekyll-paginate gem).
• A Jekyll site with a _config.yml file and a layout or page that will act as the index (commonly index.html in the site root).
• Basic familiarity with editing YAML and Liquid templates.
• Access to the site’s repository or local working copy with write permissions.

Procedure

1. Add the pagination gem

   Open the site’s Gemfile (create one if it does not exist) and ensure the following line is present:

   gem 'jekyll-paginate'

   Run Bundler to install the gem:

   # Run in the site root directory
   bundle install

   Required permissions: write access to the Gemfile and ability to execute bundle install in the project directory.

   Risk: If the gem version conflicts with other dependencies, Bundler will report an error; resolve by updating the Gemfile or using bundle update.

2. Enable pagination in _config.yml

   Add or modify these lines:

   # Number of posts per page
   paginate: 5
   # Ensure the plugin is loaded
   plugins:
     - jekyll-paginate

   The paginate value can be any positive integer; adjust to suit your design.

3. Create or edit the index layout

   If you do not already have an index.html (or a layout used as the home page), create it in the site root. Insert the following Liquid markup:

   <!-- index.html -->
   <ul>
     {% for post in paginator.posts %}
       <li>
         <a href="{{ post.url }}">{{ post.title }}</a>
         <p>{{ post.date | date: "%b %d, %Y" }}</p>
       </li>
     {% endfor %}
   </ul>
   
   <!-- Pagination navigation -->
   {% if paginator.total_pages > 1 %}
     <nav>
       {% if paginator.previous_page %}
         <a href="{{ paginator.previous_page_path }}">« Newer posts</a>
       {% endif %}
       {% if paginator.next_page %}
         <a href="{{ paginator.next_page_path }}">Older posts »</a>
       {% endif %}
     <nav>
   {% endif %}

   This loop displays the paginated posts and adds “Newer posts” / “Older posts” links using the paginator object’s paths.

4. Verify ordering (optional but recommended)

   Ensure posts are sorted newest‑first. By default Jekyll sorts site.posts by date descending, but you can enforce it in _config.yml:

   defaults:
     - scope:
         path: ""
         type: posts
       values:
         layout: "post"
     # No extra sort needed; default is date descending.

5. Build and serve the site

   Run Jekyll locally to generate the paginated output:

   # Development server with auto‑reload
   bundle exec jekyll serve
   # Or a one‑off build
   bundle exec jekyll build

   The command should be executed in the site root with the same user that owns the project files.

Expected checks

• After jekyll build, inspect the generated _site directory. You should see files such as:
• _site/index.html (first page)
• _site/page2/index.html, _site/page3/index.html, … up to _site/pageN/index.html where N = ceil(total_posts / paginate).
• Open _site/index.html in a browser and confirm that the number of post listings matches the paginate value.
• Click the “Older posts” link; the browser should load _site/page2/index.html and display the next set of posts.
• On the first page, the “Newer posts” link should be absent; on the last page, the “Older posts” link should be absent.
• Run an HTML validation tool such as htmlproofer to catch broken pagination links:

bundle exec htmlproofer ./_site

A successful run reports zero errors related to pagination.

Recovery options

If pagination produces unexpected results or you wish to disable it:

1. Remove or comment out the paginate: line and the jekyll-paginate entry from plugins: in _config.yml.
2. Optionally, delete the pagination navigation block from index.html (or restore a backup of the file).
3. Re‑run jekyll build or jekyll serve to regenerate the site without paginated pages.
4. Verify that only _site/index.html exists and that all posts appear on that single page.

Limitations

• The built‑in pagination only applies to the default posts collection. To paginate a different collection (e.g., projects), you must add a paginate_collection setting in _config.yml:

paginate_collection: "projects"

• Pagination does not work with jekyll build --incremental; a full build is required after any change to _config.yml or the index layout.
• If you use a custom layout for the home page, ensure that layout includes the Liquid pagination code; otherwise the generated pages will lack navigation.