jekyll-paginate-v2
jekyll-paginate-v2 copied to clipboard
Support real and natural custom collections in autopages
Hi, I updated the logic in autopages to properly support custom collections in a very natural way.
- Completely re-done autopage logic to be simpler and less complex, but at the same time much more flexible
- Tags and categories work the same way as always.
- Custom collections now are able to have custom filters (or not)
- Switches to using the internal system of URL's and permalinks and integrates more closely with collections in Jekyll
-
- What this means is, that it pulls data from the actual jekyll collections config. For example, it obeys
collections_dir
in jekyll, titles, url permalink, etc
- What this means is, that it pulls data from the actual jekyll collections config. For example, it obeys
- Injects ALL collection pages frontmatter + content into page, so now with autopages and the layout, you can get access to each collections frontmatter and content! Super useful!
The way this works now with a config like this
# define all your collections as usual in jekyll
# collections_dir = "foobar" // you can do this too if you want
collections:
posts:
output: true
permalink: /:categories/:title
authors:
# don't output them though, but you can set your permalink
permalink: /author/:name/
tags:
permalink: /tag/:name/
categories:
permalink: /category/:name/
autopages:
# autopage-wide enable/disable switch
enabled: true
# every collection you want to use you must make a key for and set it to enabled. Everything is disabled by default otherwise
authors:
# the layout file. This will ovveride the coll's layout; if not specified, it grabs the layout from the coll doc
layout: author-page.html
# you must enable it
enabled: true
# the key that is used by posts/whatever custom collection you want. Set this key in your collections frontmatter to filter the collection by this field
indexkey: author
# enable to filter collection by indexkey. default disabled
filter_collection: true
# obvious. Use the same key as indexkey for replacement. overrides all. If not specified, checks layout for title. If layout has no title, checks the collection doc for the title
title: "Some title :author"
# optional, but you can change the collection you're using
collection: posts
# obvious. will override docs permalink. If not specified, document's permalink will be used instead (from jekyll's collection config)
permalink: /author/:author/
# so in essence, all the above says, use the authors collection, and use the key 'author'
# to return and filter collection 'posts' by the author key (authors collection's author field == posts.author)
# so basically, it does the same thing that tags and categories does, except for custom collections
pagination:
enabled: true
# check to see debug of custom collection filter
debug: true
# this setting is honored.
collection: 'posts'
# filters custom collection by this id specified in pagination
filter_coll_by: author
# I'll specify it here now
author: Cherryleafroad
# the two options above are mainly to be used for autopages for custom coll filtering, but you can use these in regular pagination frontmatter
The purpose of indexkey
is this:
- In your author pages (e.g.
_authors/someauthor.md
), you will have a unique key in it that matches theindexkey
, in my case here it's set toauthor
. The key insidesomeauthor.md
for this example isauthor: someauthor
- This key is used to match against the collection we chose, which is by default posts. So, it will filter out all our posts which also have a key
author: someauthor
. Of course, you must also specify thefilter_collection
option to enable this
By thus doing, we have pagination for custom collections which filter out the posts with matching keys on custom collections
- I also have some changes which will take the documents frontmatter and inject it into the document (overriding current autopage values like
title
if there's a conflict), and it'll also render out the document and setpage.content
so we can access the entire collections data inside the layout as if it was a real page.
Please be gentle with me, I'm very new to Ruby and didn't even know it a week ago. Never used Ruby before
Edit: I accidentally left in a fix in here for #219. I'll just leave it there