jekyll-paginate-v2 doesn't handle pages properly

[6twenty]

There are 2 parts to this problem:

1. jekyll-paginate-v2 doesn't support pages located under the special (and relatively recent addition to Jekyll) _pages/ directory.
2. jekyll-paginate-v2 doesn't correctly copy the dir for its pagination pages.

---

1.

Jekyll now supports defining your site's regular pages under a special top-level _pages/ directory. For the most part Jekyll treats these no differently to pages that are located elsewhere, except for one key difference: these pages aren't exposed under site.pages. The reason is that files within _pages/ are treated as Document objects, while other pages are Page objects. The Document pages must be accessed via site.collections['pages'] instead; jekyll-paginate-v2 however only looks at site.pages to try to find its pagination pages.

I suspect jekyll-paginate-v2 is fairly heavily dependent on this approach though given that it sub-classes Page for its own PaginationPage class, so it would need some refactoring to support Document classes as well.

---

2.

To work around the problem above, the pagination pages must be defined outside of the _pages/ directory. In my case I have a collection of posts under the "news" category that I want to paginate, so I simply use news/index.html instead of _pages/news.html. The Page object that gets created will have page.dir #> '/news', however when jekyll-paginate-v2 clones the page, it will have page.dir #=> '/' instead. This has a knock-on effect: page.relative_path will now be index.html instead of news/index.html, and this in turn breaks the ability to use the link helper. E.g.

{% link news/index.html %}

This should work, but will instead raise an exception that the page can't be found. This is because Jekyll compares the relative_path of each file, but the relative_path for the cloned pagination page is now incorrect. This stems from this line:

@dir = File.dirname(page_to_copy.dir)

Instead of copying the dir, it's getting the parent directory name instead.

Related issue: #93

[sverrirs]

Hi Mike, thank you very much for this detailed analysis and to take the time to debug this issue.

Do you think you have time to code a fix and do the possible refactorings involved? I'd be happy to accept a PR for a fix. I'm unfortunately a bit busy with other life things and can't look into this for a while. :/

[6twenty]

For the dir issue, sure, no problem 👍

The _pages/ issue is a trickier one - I did have a brief look at making the changes for this one, but it didn't look like a quick fix. But I'll try to find time to dig into it again and see if I can get a PR together.

[sverrirs]

Thank you Mike. Any help/time you can spare is much appreciated :)

[ashmaroli]

Jekyll now supports defining your site's regular pages under a special top-level _pages/ directory.

@6twenty Where did you get that information??
For the record, this feature is not officially supported as of the latest Jekyll release v3.8.3

[6twenty]

Hey @ashmaroli - yep, you're right. This is the way we've done it for a while as it helped us keep our project organised a little better, but in looking into it this is actually more of a workaround than a supported feature. See jekyll/jekyll#920 (comment).

Interestingly the comment suggests that these pages should still get added to site.pages, which clearly isn't happening in my case and is the reason why jekyll-paginate-v2 doesn't detect these pages.

There does seem to be some desire to make _pages officially supported - this PR has a label of "Priority 2 (should)".

At any rate considering this isn't an official feature at this stage I'm happy to accept that jekyll-paginate-v2 doesn't need to concern itself with it. Hopefully it gains proper support soon 🤞

[ashmaroli]

@6twenty As of the latest release, when you add a collection labelled pages, the Ruby object site.pages doesn't get populated with the collection's entries. Instead they go into site.collections["pages"]. The latter then can be accessed via Liquid object {{ site.pages }}.