ssg  
Article Series

This article series contain few sections.


Obsolete Repository:
This article use obsolete repository. Please refer to below repository for a more recent articles.

Complete Repository

Where to Discuss?

Local Group

Preface

Goal: A Simple Pagination.

Preview

This is what we want to achieve in this tutorial.

Jekyll Pagination: Simple Positioning Indicator

More Recent Code

I have made a better code with Bulma utilizing site.pagination.permalink which you can examine at:


1: Prepare

Artefact that we need.

Includes: Pagination: Simple

Create an empty artefact. Source code used in this tutorial, is available at this repository:

  • /_includes/pagination/01-simple.html

Pages: Blog List

Set this blog list page:

  {% include pagination/01-simple.html %}

HTML Preview

The HTML that we want to achieve in this article, is similar as below.

<nav aria-label="Page navigation">
  <ul class="pagination justify-content-center">

    <!-- First Page. -->
    <li class="page-item">
      <a class="page-link" href="/demo-jekyll/pages" rel="first">First</a>
    </li>

    <!-- Previous Page. -->
    <li class="page-item">
      <a class="page-link" href="/demo-jekyll/pages/blog-4" rel="prev">Previous</a>
    </li>

    <!-- Indicator Number. -->
    <li class="page-item disabled">
      <span class="page-link">
        Page: 5 of 10</span>
    </li>

    <!-- Next Page. -->
    <li class="page-item">
      <a class="page-link" href="/demo-jekyll/pages/blog-6" rel="next">Next</a>
    </li>

    <!-- Last Page. -->
    <li class="page-item">
      <a class="page-link" href="/demo-jekyll/pages/blog-10" rel="last">Last</a>
    </li>
    
  </ul>
</nav>

We will achieve this with Jekyll code.


2: Skeleton

The Structure

Our simple pagination contain five parts:

  • First Page.

  • Previous Page.

  • Indicator Number.

  • Next Page.

  • Last Page.

Includes: Pagination: Simple

Create an empty artefact. Source code used in this tutorial, is available at this repository:

Now you need only the minimum skeleton:

{% capture spaceless %}
{% endcapture %}

<nav aria-label="Page navigation">

  {% if total_pages > 1 %}
  <ul class="pagination justify-content-center">
    <!-- First Page. -->

    <!-- Previous Page. -->

    <!-- Indicator Number. -->

    <!-- Next Page. -->

    <!-- Last Page. -->

  </ul>
  {% endif %}

</nav>

Of course, there is no need to show any pagination navigation, if we what we have is only one page. This is why we put this if total_pages > 1.

Separate Logic

Avoid useless space.

You might wonder what this capture spaceless is all about. Well…. You know.. This pagination will require complex logic later. I need to separate th logic and the view.

In order to avoid useless space, I put all logic inside this capture spaceless. You can use any variable name instead of spaceless.

Consider make a variable, for he sake of examples. Just a short version of paginator.total_pages. Because we are going to use it few times.

{% capture spaceless %}
  {% assign total_pages = paginator.total_pages %}
{% endcapture %}

3: Navigation: Previous and Next

Our minimal pagination logic would contain, only Previous Page and Next Page.

  • Previous Page
    <!-- Previous Page. -->
    {% if paginator.previous_page %}
      <li class="page-item">
        <a class="page-link" 
           href="{{ site.baseurl }}{{ paginator.previous_page_path }}" 
           rel="prev">Previous</a>
      </li>
    {% else %}
      <li class="page-item disabled">
        <span class="page-link">Previous</span>
      </li>
    {% endif %}
  • Next Page
    <!-- Next Page. -->
    {% if paginator.next_page %}
      <li class="page-item">
        <a class="page-link" 
           href="{{ site.baseurl }}{{ paginator.next_page_path }}" 
           rel="next">Next</a>
      </li>
    {% else %}
      <li class="page-item disabled">
        <span class="page-link">Next</span>
      </li>
    {% endif %}

Of course this is not enough. Our minimal pagination should show something.

Notice that the tags: rel=“prev” and rel=“next”, are html4 tags. Both are considered obsolote in html5. We are going to remove it the next article.

Browser: Pagination Preview

Jekyll Pagination: Simple Previous Next

How does it works ?

This code above rely on

  • Previous Page: if paginator.previous_page, and

  • Next Page: if paginator.next_page.

This should be self explanatory.

Stylesheet: Bootstrap Class

Bootstrap specific class are these below

  • ul: pagination

  • li: page-item

  • a, span: page-link

  • li: disabled


4: Navigation: First and Last

Consider also add first page and last page.

  • First Page
    <!-- First Page. -->
    {% unless paginator.page == 1 %}
      <li class="page-item">
        <a class="page-link"
           href="{{ site.baseurl }}{{ page.paginate_root }}" 
           rel="first">First</a>
      </li>
    {% else %}
      <li class="page-item disabled">
        <span class="page-link">First</span>
      </li>
    {% endunless %}
  • Last Page
    <!-- Last Page. -->
    {% unless paginator.page == total_pages %}
      <li class="page-item">
        <a class="page-link"
           href="{{ site.paginate_path | relative_url | replace: ':num', total_pages }}"
           rel="last">Last</a>
      </li>
    {% else %}
      <li class="page-item disabled">
        <span class="page-link">Last</span>
      </li>
    {% endunless %}

Browser: Pagination Preview

Jekyll Pagination: Simple First Last

How does it works ?

Since there is no equivalent for paginator.previous_page and paginator.next_page to show first page and last page, we utilize:

  • First Page: paginator.page == 1.

  • Last Page: paginator.page == total_pages.

Paginate Path

The paginate_path taken from official jekyll pages, does not require site.baseurl.

Notice this:

href="{{ site.paginate_path | relative_url | replace: ':num', total_pages }}"

And not this code below:

href="{{ site.baseurl }}{{ site.paginate_path | relative_url | replace: ':num', total_pages }}"

5: Active Page Indicator

And also the pagination positioning in between, in the middle of those.

    <!-- Indicator Number. -->
    <li class="page-item disabled">
      <span class="page-link">
        Page: {{ paginator.page }} of {{ total_pages }}</span>
    </li>

Browser: Pagination Preview

Hugo Pagination: Simple Positioning Indicator

How does it works ?

This just show:

Page: {{ paginator.page }} of {{ total_pages }}

6: Summary

Complete code is here below:

{% capture spaceless %}
  {% assign total_pages = paginator.total_pages %}
{% endcapture %}

<nav aria-label="Page navigation">

  {% if total_pages > 1 %}
  <ul class="pagination justify-content-center">
    <!-- First Page. -->
    {% unless paginator.page == 1 %}
      <li class="page-item">
        <a class="page-link"
           href="{{ site.baseurl }}{{ page.paginate_root }}" 
           rel="first">First</a>
      </li>
    {% else %}
      <li class="page-item disabled">
        <span class="page-link">First</span>
      </li>
    {% endunless %}

    <!-- Previous Page. -->
    {% if paginator.previous_page %}
      <li class="page-item">
        <a class="page-link" 
           href="{{ site.baseurl }}{{ paginator.previous_page_path }}" 
           rel="prev">Previous</a>
      </li>
    {% else %}
      <li class="page-item disabled">
        <span class="page-link">Previous</span>
      </li>
    {% endif %}

    <!-- Indicator Number. -->
    <li class="page-item disabled">
      <span class="page-link">
        Page: {{ paginator.page }} of {{ total_pages }}</span>
    </li>

    <!-- Next Page. -->
    {% if paginator.next_page %}
      <li class="page-item">
        <a class="page-link" 
           href="{{ site.baseurl }}{{ paginator.next_page_path }}" 
           rel="next">Next</a>
      </li>
    {% else %}
      <li class="page-item disabled">
        <span class="page-link">Next</span>
      </li>
    {% endif %}

    <!-- Last Page. -->
    {% unless paginator.page == total_pages %}
      <li class="page-item">
        <a class="page-link"
           href="{{ site.paginate_path | relative_url | replace: ':num', total_pages }}"
           rel="last">Last</a>
      </li>
    {% else %}
      <li class="page-item disabled">
        <span class="page-link">Last</span>
      </li>
    {% endunless %}
  </ul>
  {% endif %}

</nav>

What is Next ?

Consider continue reading [ Jekyll Pagination - Number ].

Thank you for reading.