From 9ac9602e22ee97a2070d819895057c2345c80f7b Mon Sep 17 00:00:00 2001 From: iBug Date: Sun, 5 May 2024 00:05:12 +0800 Subject: [PATCH] Add proper support for sverrirs' Jekyll Paginate V2 plugin (excl. AutoPages) (#2636) --- _config.yml | 26 +++++++++++- _includes/paginator-v1.html | 70 ++++++++++++++++++++++++++++++++ _includes/paginator-v2.html | 68 +++++++++++++++++++++++++++++++ _includes/paginator.html | 73 +++------------------------------- docs/_docs/05-configuration.md | 65 +++++++++++++++++++++--------- docs/_docs/10-layouts.md | 2 +- 6 files changed, 215 insertions(+), 89 deletions(-) create mode 100644 _includes/paginator-v1.html create mode 100644 _includes/paginator-v2.html diff --git a/_config.yml b/_config.yml index 5c1a4303..e616455b 100644 --- a/_config.yml +++ b/_config.yml @@ -225,9 +225,33 @@ sass: # Outputting permalink: /:categories/:title/ +timezone: # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones + + +# Pagination with jekyll-paginate paginate: 5 # amount of posts to show paginate_path: /page:num/ -timezone: # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones + +# Pagination with jekyll-paginate-v2 +# See https://github.com/sverrirs/jekyll-paginate-v2/blob/master/README-GENERATOR.md#site-configuration +# for configuration details +pagination: + # Set enabled to true to use paginate v2 + # enabled: true + debug: false + collection: 'posts' + per_page: 10 + permalink: '/page/:num/' + title: ':title - page :num' + limit: 0 + sort_field: 'date' + sort_reverse: true + category: 'posts' + tag: '' + locale: '' + trail: + before: 2 + after: 2 # Plugins (previously gems:) diff --git a/_includes/paginator-v1.html b/_includes/paginator-v1.html new file mode 100644 index 00000000..c24d4909 --- /dev/null +++ b/_includes/paginator-v1.html @@ -0,0 +1,70 @@ +{% if paginator.total_pages > 1 %} + +{% endif %} diff --git a/_includes/paginator-v2.html b/_includes/paginator-v2.html new file mode 100644 index 00000000..ea5707d5 --- /dev/null +++ b/_includes/paginator-v2.html @@ -0,0 +1,68 @@ + diff --git a/_includes/paginator.html b/_includes/paginator.html index c24d4909..c4ab29ed 100644 --- a/_includes/paginator.html +++ b/_includes/paginator.html @@ -1,70 +1,7 @@ {% if paginator.total_pages > 1 %} - + {% if site.paginate %} + {% include paginator-v1.html %} + {% elsif site.pagination.enabled %} + {% include paginator-v2.html %} + {% endif %} {% endif %} diff --git a/docs/_docs/05-configuration.md b/docs/_docs/05-configuration.md index 7f7b2b44..f4e6cd93 100644 --- a/docs/_docs/05-configuration.md +++ b/docs/_docs/05-configuration.md @@ -1008,45 +1008,72 @@ The paginator only works on files with name `index.html`. To use pagination in a paginate_path: /recent/page:num/ ``` -**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. +**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]**. {: .notice--info} [jekyll-paginate-v2]: https://github.com/sverrirs/jekyll-paginate-v2 -#### Using Jekyll Paginate V2 +### Paginate V2 -**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]. -{: .notice--info} - - [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 - -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`: +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`: ```yaml -# Pagination with jekyll-paginate-v2 -# See https://github.com/sverrirs/jekyll-paginate-v2/blob/master/README-GENERATOR.md#site-configuration -# for configuration details pagination: enabled: true - debug: false collection: 'posts' - per_page: 10 - permalink: '/page/:num/' + per_page: 5 + permalink: '/page/:num/' # Pages are index.html inside this folder (default) title: ':title - page :num' limit: 0 sort_field: 'date' sort_reverse: true - category: 'posts' - tag: '' - locale: '' trail: before: 2 after: 2 ``` -Minimal Mistakes will automatically pick up Jekyll Paginate V2 mode if it detects the `pagination.enabled` setting in `_config.yml`. +Then, create `/posts/index.html` with the following content: -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. +```html +--- +title: "Posts" +layout: home +permalink: /posts/ +pagination: + enabled: true +--- +``` + +Your posts will be paginated at `/posts/`, `/posts/page/2/` and `/posts/page/3/` etc. + +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: + +```html +--- +title: "Lovely pets" +layout: home +permalink: /pets/ +pagination: + enabled: true + collection: + - cat + - dog +--- +``` + +**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. + +```yaml +pagination: + + # Optional, the default file extension for generated pages (e.g html, json, xml). + # Internally this is set to html by default + extension: html + + # Optional, the default name of the index file for generated pages (e.g. 'index.html') + # Without file extension + indexpage: 'index' +``` ### Timezone diff --git a/docs/_docs/10-layouts.md b/docs/_docs/10-layouts.md index 3f20ea02..1760f96d 100644 --- a/docs/_docs/10-layouts.md +++ b/docs/_docs/10-layouts.md @@ -365,7 +365,7 @@ Then adjust the `paginate_path` in **_config.yml** to match. paginate_path: /blog/page:num ``` -**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. +**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). {: .notice--info} **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.