Skip to content

Latest commit

 

History

History
117 lines (87 loc) · 5.88 KB

README-AUTOPAGES.md

File metadata and controls

117 lines (87 loc) · 5.88 KB
Raw

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 written and graciously donated by Stephen Crosby. Thanks! :)

⚠️ Please note, this feature is still experimental and might not be ready for production yet.

Site configuration

############################################################
# 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.

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.

<h1 class="page-heading">All pages tagged with <b>{% if page.autopages %}{{page.autopages.display_name}}{% endif %}</b></h1>

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 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. 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