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! :)

• Site configuration
• Simple configuration
  • Obtaining the original Tag or Category name
• Advanced configuration
• Specialised pages
• Considerations
  • Title should not contain pagination macros
• Example Sites
• Common issues

:warning: 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'

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

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

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.

Categories and tags with spaces

If you have category or tag names with spaces, make sure you use either

1. the singular forms (tag, category), or
2. the plural forms (tags, categories) using the YAML array syntax.

See Filtering categories for more information.

Special characters

As of v1.9.4, special characters are supported in category, tag, and collection names by default:

  category: sports car, b+w

If you need to support the previous behavior where special characters are replaced with hyphens in URLs, use the new slugify option:

autopages:
  categories:
    enabled: true
    slugify:
      mode: nil
      cased: true

The following modes are available:

Value	Description
none	No conversion (default)
raw	Replace sequences of spaces with a hyphen
nil	Replace non-alphabetic characters with a hyphen
pretty	Keep some non-alphabetic characters (._~!$&'()+,;=@)

If cased is set to true, all uppercase letters are replaced with their lowercase counterparts.

Common issues

None reported so far