Skip to content

Commit 1f51373

Browse files
iBugiBug
authored
Add proper support for sverrirs' Jekyll Paginate V2 plugin (excl. AutoPages) (mmistakes#2636)
1 parent 6270161 commit 1f51373

File tree

6 files changed

+215
-89
lines changed

6 files changed

+215
-89
lines changed

‎_config.yml

+25-1
Original file line numberDiff line numberDiff line change
@@ -225,9 +225,33 @@ sass:
225225

226226
# Outputting
227227
permalink: /:categories/:title/
228+
timezone: # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
229+
230+
231+
# Pagination with jekyll-paginate
228232
paginate: 5 # amount of posts to show
229233
paginate_path: /page:num/
230-
timezone: # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
234+
235+
# Pagination with jekyll-paginate-v2
236+
# See https://github.com/sverrirs/jekyll-paginate-v2/blob/master/README-GENERATOR.md#site-configuration
237+
# for configuration details
238+
pagination:
239+
# Set enabled to true to use paginate v2
240+
# enabled: true
241+
debug: false
242+
collection: 'posts'
243+
per_page: 10
244+
permalink: '/page/:num/'
245+
title: ':title - page :num'
246+
limit: 0
247+
sort_field: 'date'
248+
sort_reverse: true
249+
category: 'posts'
250+
tag: ''
251+
locale: ''
252+
trail:
253+
before: 2
254+
after: 2
231255

232256

233257
# Plugins (previously gems:)

‎_includes/paginator-v1.html

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
{% if paginator.total_pages > 1 %}
2+
<nav class="pagination">
3+
{% assign paginate_path_last = site.paginate_path | split: '/' | last %}
4+
{% assign first_page_path = paginator.first_page_path | default: site.paginate_path | replace: paginate_path_last, '' | replace: '//', '/' | relative_url %}
5+
<ul>
6+
{% comment %} Link for previous page {% endcomment %}
7+
{% if paginator.previous_page %}
8+
{% if paginator.previous_page == 1 %}
9+
<li><a href="{{ first_page_path }}">{{ site.data.ui-text[site.locale].pagination_previous | default: "Previous" }}</a></li>
10+
{% else %}
11+
<li><a href="{{ site.paginate_path | replace: ':num', paginator.previous_page | replace: '//', '/' | relative_url }}">{{ site.data.ui-text[site.locale].pagination_previous | default: "Previous" }}</a></li>
12+
{% endif %}
13+
{% else %}
14+
<li><a href="#" class="disabled"><span aria-hidden="true">{{ site.data.ui-text[site.locale].pagination_previous | default: "Previous" }}</span></a></li>
15+
{% endif %}
16+
17+
{% comment %} First page {% endcomment %}
18+
{% if paginator.page == 1 %}
19+
<li><a href="#" class="disabled current">1</a></li>
20+
{% else %}
21+
<li><a href="{{ first_page_path }}">1</a></li>
22+
{% endif %}
23+
24+
{% assign page_start = 2 %}
25+
{% if paginator.page > 4 %}
26+
{% assign page_start = paginator.page | minus: 2 %}
27+
{% comment %} Ellipsis for truncated links {% endcomment %}
28+
<li><a href="#" class="disabled">&hellip;</a></li>
29+
{% endif %}
30+
31+
{% assign page_end = paginator.total_pages | minus: 1 %}
32+
{% assign pages_to_end = paginator.total_pages | minus: paginator.page %}
33+
{% if pages_to_end > 4 %}
34+
{% assign page_end = paginator.page | plus: 2 %}
35+
{% endif %}
36+
37+
{% for index in (page_start..page_end) %}
38+
{% if index == paginator.page %}
39+
<li><a href="{{ site.paginate_path | replace: ':num', index | replace: '//', '/' | relative_url }}" class="disabled current">{{ index }}</a></li>
40+
{% else %}
41+
{% comment %} Distance from current page and this link {% endcomment %}
42+
{% assign dist = paginator.page | minus: index %}
43+
{% if dist < 0 %}
44+
{% comment %} Distance must be a positive value {% endcomment %}
45+
{% assign dist = 0 | minus: dist %}
46+
{% endif %}
47+
<li><a href="{{ site.paginate_path | replace: ':num', index | relative_url }}">{{ index }}</a></li>
48+
{% endif %}
49+
{% endfor %}
50+
51+
{% comment %} Ellipsis for truncated links {% endcomment %}
52+
{% if pages_to_end > 3 %}
53+
<li><a href="#" class="disabled">&hellip;</a></li>
54+
{% endif %}
55+
56+
{% if paginator.page == paginator.total_pages %}
57+
<li><a href="#" class="disabled current">{{ paginator.page }}</a></li>
58+
{% else %}
59+
<li><a href="{{ site.paginate_path | replace: ':num', paginator.total_pages | replace: '//', '/' | relative_url }}">{{ paginator.total_pages }}</a></li>
60+
{% endif %}
61+
62+
{% comment %} Link next page {% endcomment %}
63+
{% if paginator.next_page %}
64+
<li><a href="{{ site.paginate_path | replace: ':num', paginator.next_page | replace: '//', '/' | relative_url }}">{{ site.data.ui-text[site.locale].pagination_next | default: "Next" }}</a></li>
65+
{% else %}
66+
<li><a href="#" class="disabled"><span aria-hidden="true">{{ site.data.ui-text[site.locale].pagination_next | default: "Next" }}</span></a></li>
67+
{% endif %}
68+
</ul>
69+
</nav>
70+
{% endif %}

‎_includes/paginator-v2.html

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<nav class="pagination">
2+
<ul>
3+
{% comment %} Link for previous page {% endcomment %}
4+
{% if paginator.previous_page %}
5+
{% if paginator.previous_page == 1 %}
6+
<li><a href="{{ paginator.first_page_path | relative_url }}">{{ site.data.ui-text[site.locale].pagination_previous | default: "Previous" }}</a></li>
7+
{% else %}
8+
<li><a href="{{ paginator.previous_page_path | relative_url }}">{{ site.data.ui-text[site.locale].pagination_previous | default: "Previous" }}</a></li>
9+
{% endif %}
10+
{% else %}
11+
<li><a href="#" class="disabled"><span aria-hidden="true">{{ site.data.ui-text[site.locale].pagination_previous | default: "Previous" }}</span></a></li>
12+
{% endif %}
13+
14+
{% comment %} Determine whether the first page and the last page are already included in trail {% endcomment %}
15+
{% for trail in paginator.page_trail %}
16+
{% if trail.num == paginator.first_page %}
17+
{% assign has_first_page = true %}
18+
{% elsif trail.num == paginator.last_page %}
19+
{% assign has_last_page = true %}
20+
{% endif %}
21+
{% endfor %}
22+
23+
{% comment %} First page {% endcomment %}
24+
{% unless has_first_page %}
25+
{% if paginator.page == 1 %}
26+
<li><a href="#" class="disabled current">1</a></li>
27+
{% else %}
28+
<li><a href="{{ paginator.first_page_path | relative_url }}">1</a></li>
29+
{% endif %}
30+
{% endunless %}
31+
32+
{% comment %} Ellipsis for truncated links {% endcomment %}
33+
{% assign ellipsis_start = paginator.first_page | plus: 1 %}
34+
{% if paginator.page_trail.first.num > ellipsis_start %}
35+
<li><a href="#" class="disabled">&hellip;</a></li>
36+
{% endif %}
37+
38+
{% comment %} Main pagination trail {% endcomment %}
39+
{% for trail in paginator.page_trail %}
40+
{% if paginator.page == trail.num %}
41+
<li><a href="{{ trail.path | remove: 'index.html' | relative_url }}" class="disabled current">{{ trail.num }}</a></li>
42+
{% else %}
43+
<li><a href="{{ trail.path | remove: 'index.html' | relative_url }}">{{ trail.num }}</a></li>
44+
{% endif %}
45+
{% endfor %}
46+
47+
{% comment %} Ellipsis for truncated links {% endcomment %}
48+
{% assign ellipsis_end = paginator.last_page | minus: 1 %}
49+
{% if paginator.page_trail.last.num < ellipsis_end %}
50+
<li><a href="#" class="disabled">&hellip;</a></li>
51+
{% endif %}
52+
53+
{% unless has_last_page %}
54+
{% if paginator.page == paginator.total_pages %}
55+
<li><a href="#" class="disabled current">{{ paginator.page }}</a></li>
56+
{% else %}
57+
<li><a href="{{ paginator.last_page_path | remove: 'index.html' | relative_url }}">{{ paginator.total_pages }}</a></li>
58+
{% endif %}
59+
{% endunless %}
60+
61+
{% comment %} Link next page {% endcomment %}
62+
{% if paginator.next_page %}
63+
<li><a href="{{ paginator.next_page_path | remove: 'index.html' | relative_url }}">{{ site.data.ui-text[site.locale].pagination_next | default: "Next" }}</a></li>
64+
{% else %}
65+
<li><a href="#" class="disabled"><span aria-hidden="true">{{ site.data.ui-text[site.locale].pagination_next | default: "Next" }}</span></a></li>
66+
{% endif %}
67+
</ul>
68+
</nav>

‎_includes/paginator.html

+5-68
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,7 @@
11
{% if paginator.total_pages > 1 %}
2-
<nav class="pagination">
3-
{% assign paginate_path_last = site.paginate_path | split: '/' | last %}
4-
{% assign first_page_path = paginator.first_page_path | default: site.paginate_path | replace: paginate_path_last, '' | replace: '//', '/' | relative_url %}
5-
<ul>
6-
{% comment %} Link for previous page {% endcomment %}
7-
{% if paginator.previous_page %}
8-
{% if paginator.previous_page == 1 %}
9-
<li><a href="{{ first_page_path }}">{{ site.data.ui-text[site.locale].pagination_previous | default: "Previous" }}</a></li>
10-
{% else %}
11-
<li><a href="{{ site.paginate_path | replace: ':num', paginator.previous_page | replace: '//', '/' | relative_url }}">{{ site.data.ui-text[site.locale].pagination_previous | default: "Previous" }}</a></li>
12-
{% endif %}
13-
{% else %}
14-
<li><a href="#" class="disabled"><span aria-hidden="true">{{ site.data.ui-text[site.locale].pagination_previous | default: "Previous" }}</span></a></li>
15-
{% endif %}
16-
17-
{% comment %} First page {% endcomment %}
18-
{% if paginator.page == 1 %}
19-
<li><a href="#" class="disabled current">1</a></li>
20-
{% else %}
21-
<li><a href="{{ first_page_path }}">1</a></li>
22-
{% endif %}
23-
24-
{% assign page_start = 2 %}
25-
{% if paginator.page > 4 %}
26-
{% assign page_start = paginator.page | minus: 2 %}
27-
{% comment %} Ellipsis for truncated links {% endcomment %}
28-
<li><a href="#" class="disabled">&hellip;</a></li>
29-
{% endif %}
30-
31-
{% assign page_end = paginator.total_pages | minus: 1 %}
32-
{% assign pages_to_end = paginator.total_pages | minus: paginator.page %}
33-
{% if pages_to_end > 4 %}
34-
{% assign page_end = paginator.page | plus: 2 %}
35-
{% endif %}
36-
37-
{% for index in (page_start..page_end) %}
38-
{% if index == paginator.page %}
39-
<li><a href="{{ site.paginate_path | replace: ':num', index | replace: '//', '/' | relative_url }}" class="disabled current">{{ index }}</a></li>
40-
{% else %}
41-
{% comment %} Distance from current page and this link {% endcomment %}
42-
{% assign dist = paginator.page | minus: index %}
43-
{% if dist < 0 %}
44-
{% comment %} Distance must be a positive value {% endcomment %}
45-
{% assign dist = 0 | minus: dist %}
46-
{% endif %}
47-
<li><a href="{{ site.paginate_path | replace: ':num', index | relative_url }}">{{ index }}</a></li>
48-
{% endif %}
49-
{% endfor %}
50-
51-
{% comment %} Ellipsis for truncated links {% endcomment %}
52-
{% if pages_to_end > 3 %}
53-
<li><a href="#" class="disabled">&hellip;</a></li>
54-
{% endif %}
55-
56-
{% if paginator.page == paginator.total_pages %}
57-
<li><a href="#" class="disabled current">{{ paginator.page }}</a></li>
58-
{% else %}
59-
<li><a href="{{ site.paginate_path | replace: ':num', paginator.total_pages | replace: '//', '/' | relative_url }}">{{ paginator.total_pages }}</a></li>
60-
{% endif %}
61-
62-
{% comment %} Link next page {% endcomment %}
63-
{% if paginator.next_page %}
64-
<li><a href="{{ site.paginate_path | replace: ':num', paginator.next_page | replace: '//', '/' | relative_url }}">{{ site.data.ui-text[site.locale].pagination_next | default: "Next" }}</a></li>
65-
{% else %}
66-
<li><a href="#" class="disabled"><span aria-hidden="true">{{ site.data.ui-text[site.locale].pagination_next | default: "Next" }}</span></a></li>
67-
{% endif %}
68-
</ul>
69-
</nav>
2+
{% if site.paginate %}
3+
{% include paginator-v1.html %}
4+
{% elsif site.pagination.enabled %}
5+
{% include paginator-v2.html %}
6+
{% endif %}
707
{% endif %}

‎docs/_docs/05-configuration.md

+46-19
Original file line numberDiff line numberDiff line change
@@ -1008,45 +1008,72 @@ The paginator only works on files with name `index.html`. To use pagination in a
10081008
paginate_path: /recent/page:num/
10091009
```
10101010

1011-
**Please note:** When using Jekyll's default [pagination plugin](https://jekyllrb.com/docs/pagination/) `paginator.posts` can only be called once. If you're looking for something more powerful that can paginate category, tag, and collection pages, [**jekyll-paginate-v2**][jekyll-paginate-v2] is the way to go.
1011+
**Please note:** When using Jekyll's default [pagination plugin](https://jekyllrb.com/docs/pagination/) `paginator.posts` can only be called once. If you're looking for something more powerful that can paginate category, tag, and collection pages I suggest **[jekyll-paginate-v2][jekyll-paginate-v2]**.
10121012
{: .notice--info}
10131013

10141014
[jekyll-paginate-v2]: https://github.com/sverrirs/jekyll-paginate-v2
10151015

1016-
#### Using Jekyll Paginate V2
1016+
### Paginate V2
10171017

1018-
**Note:** Jekyll Paginate V2 is **not** available on GitHub Pages. You must build your site locally or with a CI service like [GitHub Actions][gh-pages-actions].
1019-
{: .notice--info}
1020-
1021-
[gh-pages-actions]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow
1022-
1023-
If you opt to use [Jekyll Paginate V2][jekyll-paginate-v2], remove `paginate` from `_config.yml` and add the following configuration to your `_config.yml`:
1018+
If you're using [Jekyll Paginate V2][jekyll-paginate-v2], you can enjoy its powerful features by removing `paginate` and `paginate_path` and adding the following configuration to your `_config.yml`:
10241019

10251020
```yaml
1026-
# Pagination with jekyll-paginate-v2
1027-
# See https://github.com/sverrirs/jekyll-paginate-v2/blob/master/README-GENERATOR.md#site-configuration
1028-
# for configuration details
10291021
pagination:
10301022
enabled: true
1031-
debug: false
10321023
collection: 'posts'
1033-
per_page: 10
1034-
permalink: '/page/:num/'
1024+
per_page: 5
1025+
permalink: '/page/:num/' # Pages are index.html inside this folder (default)
10351026
title: ':title - page :num'
10361027
limit: 0
10371028
sort_field: 'date'
10381029
sort_reverse: true
1039-
category: 'posts'
1040-
tag: ''
1041-
locale: ''
10421030
trail:
10431031
before: 2
10441032
after: 2
10451033
```
10461034

1047-
Minimal Mistakes will automatically pick up Jekyll Paginate V2 mode if it detects the `pagination.enabled` setting in `_config.yml`.
1035+
Then, create `/posts/index.html` with the following content:
10481036

1049-
While the plugin allows you to change the `indexpage` and the `extension` (which default to `index` and `html` respectively), Minimal Mistakes do not support non-default values for these settings, so you should keep them as-is.
1037+
```html
1038+
---
1039+
title: "Posts"
1040+
layout: home
1041+
permalink: /posts/
1042+
pagination:
1043+
enabled: true
1044+
---
1045+
```
1046+
1047+
Your posts will be paginated at `/posts/`, `/posts/page/2/` and `/posts/page/3/` etc.
1048+
1049+
Similarly, if you want to paginate a collection or a tag, you can create another `index.html` at an appropriate location, and add configuration to the `pagination` key in the front matter, like this:
1050+
1051+
```html
1052+
---
1053+
title: "Lovely pets"
1054+
layout: home
1055+
permalink: /pets/
1056+
pagination:
1057+
enabled: true
1058+
collection:
1059+
- cat
1060+
- dog
1061+
---
1062+
```
1063+
1064+
**Note:** There are two more configuration options from Jekyll Paginate V2 that this theme doesn't support yet. You should either leave them out or use their default values as shown below. Changing them may lead to unexpected results and you're on your own.
1065+
1066+
```yaml
1067+
pagination:
1068+
1069+
# Optional, the default file extension for generated pages (e.g html, json, xml).
1070+
# Internally this is set to html by default
1071+
extension: html
1072+
1073+
# Optional, the default name of the index file for generated pages (e.g. 'index.html')
1074+
# Without file extension
1075+
indexpage: 'index'
1076+
```
10501077

10511078
### Timezone
10521079

‎docs/_docs/10-layouts.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -365,7 +365,7 @@ Then adjust the `paginate_path` in **_config.yml** to match.
365365
paginate_path: /blog/page:num
366366
```
367367

368-
**Note:** Jekyll can only paginate a single `index.html` file. If you'd like to paginate more pages (e.g. category indexes) you'll need the help of a custom plugin. For more pagination related settings check the [**Configuration**]({{ "/docs/configuration/#paginate" | relative_url }}) section.
368+
**Note:** The default Jekyll Paginate plugin can only paginate a single `index.html` file. If you'd like to paginate more pages (e.g. category indexes) you'll need the help of a custom plugin. For more pagination-related settings check the [**Configuration**]({{ "/docs/configuration/#paginate" | relative_url }}) section, including settings for [Jekyll Paginate V2](https://github.com/sverrirs/jekyll-paginate-v2).
369369
{: .notice--info}
370370

371371
**Note:** By default, documents are shown in a list view. To change to a grid view add `entries_layout: grid` to the page's front matter. To increase the width of the main container, giving more space to the grid items also add `classes: wide` to the home page's YAML Front Matter.

0 commit comments

Comments
 (0)