Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sverrirs/jekyll-paginate-v2

Pagination Generator for Jekyll 3 (enhanced replacement for the old built-in jekyll-paginate gem) ⛺
https://github.com/sverrirs/jekyll-paginate-v2

dynamic jekyll jekyll-paginate jekyll-plugin paginate pagination pagination-gem pagination-generator pagination-logic pagination-pages

Last synced: 2 days ago
JSON representation

Pagination Generator for Jekyll 3 (enhanced replacement for the old built-in jekyll-paginate gem) ⛺

Awesome Lists containing this project

README 

        
# Jekyll::Paginate V2::AutoPages



**AutoPages** are an optional pagination addon that can automatically generate paginated pages for all your collections, tags and categories used in the pages on your site. This is useful if you have a large site where paginating the contents of your collections, tags or category lists provides a better user experience.





  




> This feature is based on [code](https://github.com/stevecrozz/lithostech.com/blob/master/_plugins/tag_indexes.rb) written and graciously donated by [Stephen Crosby](https://github.com/stevecrozz). Thanks! :)



* [Site configuration](#site-configuration)

* [Simple configuration](#simple-configuration)

  + [Obtaining the original Tag or Category name](#obtaining-the-original-tag-or-category-name)

* [Advanced configuration](#advanced-configuration)

* [Specialised pages](#specialised-pages)

* [Considerations](#considerations)

  + [Title should not contain pagination macros](#title-should-not-contain-pagination-macros)

* [Example Sites](https://github.com/sverrirs/jekyll-paginate-v2/tree/master/examples)

* [Common issues](#common-issues)



:warning: Please note, this feature is still **experimental** and might not be ready for production yet.



## Site configuration



``` yml

############################################################

# Site configuration for the Auto-Pages feature

# The values here represent the defaults if nothing is set

autopages:



  # Site-wide kill switch, disable here and it doesn't run at all 

  enabled: false



  # Category pages, omit entire config element to disable

  categories: 

    # Optional, the list of layouts that should be processed for every category found in the site

    layouts: 

      - 'autopage_category.html'

    # Optional, the title that each category paginate page should get (:cat is replaced by the Category name)

    title: 'Posts in category :cat'

    # Optional, the permalink for the  pagination page (:cat is replaced), 

    # the pagination permalink path is then appended to this permalink structure

    permalink: '/category/:cat'

    # Optional, when true logging related to category pages will be supressed.

    silent: false

    slugify:

      mode: 'default'   # :cat is slugified. Modes: default, raw, pretty, ascii, latin

      case: false       # Whether to replace all uppercase letters with their lowercase counterparts



  # Collection pages, omit to disable

  collections:

    layouts: 

      - 'autopage_collection.html'

    title: 'Posts in collection :coll' # :coll is replaced by the collection name

    permalink: '/collection/:coll'

    silent: false

    slugify:

      mode: 'default'   # :coll is slugified.

      case: false 

  

  # Tag pages, omit to disable

  tags:

    layouts: 

      - 'autopage_tags.html'

    title: 'Posts tagged with :tag' # :tag is replaced by the tag name

    permalink: '/tag/:tag'

    silent: false

    slugify:

      mode: 'default'   # :tag is slugified.

      case: false

```



## Simple configuration

The only thing needed to enable the auto pages is to add the configuration element to the site.config file and then create a layout that the pages should use.



Example of a simple autopage layout can be seen in Example 3 [examples/03-tags/_layouts/autopage_tags.html](https://github.com/sverrirs/jekyll-paginate-v2/blob/master/examples/03-tags/_layouts/autopage_tags.html).



The layout does not need anything special beyond the normal pagination logic (e.g. `for post in paginator.posts` and then the next/prev arrows). You can either name the layouts by the default names (see site configuration section above) or give them a custom name and add them to the `layouts:` configuration for the relevant type of autopage.



### Obtaining the original Tag or Category name

Internally the autopage system will trim and downcase the indexing key (tag, category or collection name). To retrieve the original name of the index key you can use the `autopages.display_name` liquid variable.



``` html

All pages tagged with {% if page.autopages %}{{page.autopages.display_name}}{% endif %}



```



This variable returns the untouched key value. As an example if your site uses the tag `Science-Fiction` then



```

page.tag = "science-fiction"

page.autopages.display_name = "Science-Fiction"

```



See [#6](https://github.com/sverrirs/jekyll-paginate-v2/issues/6) for more information.



## Advanced configuration

You can customize the look an feel of the permalink structure and the title for the auto-pages. You can also add front-matter `pagination` configuration to the layout pages you're using to specify things like sorting, filtering and all the other configuration options that are available in the normal pagination generator.



> Keep in mind that when the autopages are paginated the pagination permalink structure and pagination title suffix is appended to them.



## Specialised pages



Special autopages can be used that leverage the powerful filtering and sorting features of the pagination logic. For example you might want to create special pages autopages that paginate all tags in a certain collection or certain tags within a category.



To achieve this you specify the `pagination` front-matter configuration in the autopage layout file.



An example of this can be found in [examples/03-tags/_layouts/autopage_collections_tags.html](https://github.com/sverrirs/jekyll-paginate-v2/blob/master/examples/03-tags/_layouts/autopage_collections_tags.html). This page creates paginated pages for all tags that are found in the special _all_ collections.



## Considerations



### Title should not contain pagination macros

There is no need to include the pagination title macros `:num`, `:max` or `:title` in the title configuration. The autopages will use the title configuration from the pagination configuration itself.



## Common issues

_None reported so far_