The post below is long, longer than I tought it'll be, but please read it all 😄
I hope that others including the maintainers of the project, have similar toughts on the topic and see it as a way to go forward with the project making it more feature rich and customizeable even for more complex web pages. My intention is not to fragmentize the community, thats why I posted my ideas here instead of creating another fork and just doing "my stuff".
Why I'm doing this?
Hello, like others here I'm dedicated Jekyll user and have built many websites, including my own, on Jekyll.
The most time consuming part was to find a suitable solution to produce multilingual site with customized and filtered pagination pages. Currently Jekyll pagination has no support for that. Yes, there are a lot of alternatives, each of them have different goal, but any of them exactly suitable for my needs - lack of documentation and sometimes hard or even overkill to implement.
I propose to write all new Jekyll pagination system, from scratch. Some of You might ask, why write here, why I don't just fork it and make my changes? Well I kind of did that already, but this is not the solution.
In my opinion projects like this should be kept together and developed as one which guarantees one good source of the software.
My idea is to start from scratch (we could reuse useful code), create an experimental repository, but first we should map our needs, toughts and other hardcore awesome ideas.
The ideas listed below are my personal toughts on the subject, feel free to express Your toughts. The ideas are based on my experience and from issues of the project.
If maintainers think that I'm overstepping my boundaries (I hope that I'm not 😃), feel free to close and lock this issue.
What I would like to achieve?
Architecture
Current architecture is limited only to posts. Referring to #22 I think it should be able to paginate all Jekyll content types: pages, posts and collections.
Code clarity
Make classes independent (#26). Currently there's huge hell in Pager class. The class should be completely independent and all variables should be passed to it as separate and well defined arguments.
Layouts/templates
Jekyll has a well defined layout system and for clarity we should use it instead of defining html files directly and relative of the root directory. Defining layout like myblog whould use template _layouts/myblog.html.
Pemalinks
With this way we should also separate layout from permalinks (#22). This would make a life lot of easier for multilingual page. Default permalink should point to the layout, if layout is myblog then permalink is /myblog:num. The first page is /myblog.html unless, there is a missing index.html in the same directory, then the first page is /index.html. Other pages would still be /myblog2/index.html, /myblog3/index.html etc.
Filtering
When converting my site to multilingual I researched some other plug-ins which added support for pagination by category. Since Jekyll is in my opinion pretty abstract we shouldn't focus on one filter variable category, but it should be configureable (for example, I filter my posts using language). We should also keep in mind that the frontmatter variables can have multiple values so support for lists as filter value is needed (eg filter posts by language values [ "et_EE", "en_US" ]). Also support for both include and exclude filters would be a good feature (include all category X, but exclude if also in category Y).
Sorting
Custom sorting would be awesome feature. The default should be same behavior as now (by date descending), but we should make it configurable, so we could use other fontmatter variables and values for sorting, try to detect automatically if alphabetically or chronologically. For pages and collections the default should by filename alphabetically ascending.
Avoiding existing mistakes
Both open and closed issues should be taken in consideration when building new system so we don't step on the same rake over and over again.
Compatibility
Everything must be backwards compatible. The new code must support the old config layout otherwise a lot of web pages will break and that's not acceptable.
Proposed config syntax (based on #22)
I'm proposing the configuration syntax below.
pagination:
# Allow setting global default limits for all paginated pages
limit: 0 # Limit how many content objects to paginate (default: 0, means all)
page_limit: 10 # How many objects per page, used to be `paginate` (default: 0, means all)
filter:
# If filter is not specified or is null then all objects are
# considered included
include:
locale: en_US
posts:
# The global settings `limit` and `page_limit` are included here
# but can be overwritten
- page_limit: 15
layout: blog # Which layout to use from `_layouts/`
# permalink: /blog:num # Permalink syntax, used to be `paginate_path` (the default is taken from layout)
filter:
include:
# en_US is included from global filters settings, et_EE and
# de_DE are appended.
locale:
- et_EE
- de_DE
exclude:
category:
- drafts
- layout: blog_et_EE # Another posts paginator.
permalink: /et/blog/:num # Note: /et/blog/:num and /et/blog:num are behaving differently
filter:
include: et_EE
exclude: en_US
sort:
date: asc
pages:
- layout: pages
permalink: /pages/:num
sort:
title: desc
collections:
# The collections are defined here not on the root node, because
# this behavior would eliminate conflicts with global pagination
# settings
- authors:
limit: 50
# layout: authors # By default, taken from collection name
# permalink: /authors:num # By default, taken from collection name
filter: null # Disable filtering, otherwise global filters will applyNote, that if posts, pages or collections are not defined as lists, then those objects are not considered as multipagination (if you only want one pagination page, then You can use associative arrays directly as those node's values:
pagination:
posts:
layout: blog
The code above would also be the shortest code to enable pagination for posts. There is no need to define permalink here and if You don't have /index.html then default permalink is considered to be that, but if You do, then first page will be /blog.html (see the Permalinks paragraph).
How could I achieve that?
As stated in the introduction, the idea is to create an experimental repository (milestone 2.0.0?) which would contain all the new Jekyll pagination. We all have our daily jobs to do, so this probably won't be finished this month, not even next or even might not be in this year, but we would have a straight goal and sight where to go next. All useful contributions from everyone would be welcome 😄 .
How can You help?
I'm slightly new to Ruby world, but I have extensive and long time knowledge of PHP, Python, various *nix shells' script languages etc. To be honest those two commits from my fork's experimental branch are basically my first serious contact with Ruby world.
Note: I don not encourage nor recommend to use this code in production, it's not a solution to existing issues, it's a hack which I quickly made to add multilingual support to my site.
Yes, I can write the code but I have no knowledge of other Ruby stuff including inline documenting, unit testing, packaging and distribution - so thats where the most of help would be needed.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent