Preface
Goal: A Simple Pagination.
Preview
This is what we want to achieve in this tutorial.
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:
- /pages/index.html : github.com/…/pages/index.html.
{% 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:
-
- /_includes/pagination/01-simple.html
- gitlab.com/…/_includes/pagination/01-simple.html
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
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
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
How does it works ?
This just show:
Page: {{ paginator.page }} of {{ total_pages }}
6: Summary
Complete code is here below:
-
- /_includes/pagination/01-simple.html
- gitlab.com/…/_includes/pagination/01-simple.html
{% 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.