jekyll-paginate-v2 icon indicating copy to clipboard operation
jekyll-paginate-v2 copied to clipboard

Support real and natural custom collections in autopages

Open MolotovCherry opened this issue 2 years ago • 0 comments

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
  • 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 the indexkey, in my case here it's set to author. The key inside someauthor.md for this example is author: 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 the filter_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 set page.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

MolotovCherry avatar Mar 31 '22 23:03 MolotovCherry