[RFC] Pagination feature

[Geobert]

Feature to paginate a collection of documents so we can avoid a landing page which is
thousands of kilometer long :p

Requirements

• Documentation
• Audit
  • What do we call "pagination" #680
  • What should the case for string values be? #679
  • Should we get rid of every "pages" page being an index? #681

Initial

Index pages should be able to index by

• all content
• A single tag
• Categories
• published_date year, year and month or year and month and day

Index pages should be able to sort by multiple factors at once:

• published_date
• weight (helpful for "pinning" some content to top)
• title

Index page behavior

• Access to:
  • Ability to create back, forward, first, last, and index-based links
• Not part of collections.<name>.pages

Index page permalinks

• Able to define permalink with current pagination index
  • Should we ensure there is a way to avoid a 0 when that is the index?
• Content we are indexing by is available for permalink
  • categories list is only as long as where we are currently indexing
  • Make date variables that aren't part of the index nil? Like day variables when indexing by month.
  • Can you define category or publish_date for a index? How do these interact?
• Internal links ([RFC] Internal linking #440) would map to index=0

Potential

Narrowing and nesting

• Should we support narrowing by additional tags?
• Nested indexing
  • tags within a category
  • published_date within category

Unplanned

Index pages should be able to index by

• Should we support hierarchical tags (like parent::child)?

Proposal

Activation

This feature is activated in the frontmatter.

Default values and use shortcut include to activate indexing:

pagination:
  include: Categories // default: `None`, can also be `All`, `Tags` `Dates`, etc
  per_page: 10
  permalink_suffix: "./{{index}}/{{ num }}/"
  order: Desc
  sort_by: ["weight", "published_date"]
  trails:
    before: 0
    after: 0

Also, we can make the schema auto-adapt

• pagination: true maps to pagination: All
• pagination: categories
• pagination: categories, tags

User-defined defaults can be set in _cobalt.yml by filling in the default,
pages.default, or posts.default pagination field, just leaving include as None
to avoid activating it for all pages.

Permalink

This permalink attribute is not to be confused with the one outside pagination section.
It defines the location of the generated indexes.

New permalink attributes specific to this context

• include: a built-in representation of the paginated concept
• num: the index number

Paginator

Pagination would be accessible through a paginator object (total ripoff from jekyll's
pagination v2):

pages: The list of posts objects that belong to this pagination page.
total_pages: Total number of pages contained in this paginator.
per_page: Maximum number of posts or documents on each pagination page.

index: Current index.
indexes: All paginators available, one per index (used in cases like Tags, nil otherwise).
index_permalink: The relative Url path of the current pagination page.
total_indexes: Total number of pagination pages created.
previous_index_permalink: 	The relative Url of the previous page. Nil if no previous page is available.
next_index_permalink: The relative Url of the next page in the pagination. Nil if there is no next page available.
first_index_permalink: The relative Url of the first page in the pagination.
last_index_permalink: The relative Url of the last page in the pagination.

trails: The pagination trail structure
    before: 0
    after: 0

Once activated, a paginator object replace collection object in liquid template.

Tags

Moved to RFC https://github.com/cobalt-org/cobalt.rs/issues/549

Publication Date

Open Question

• How do we let users select how much of the date to index by?
  • Have a field that is a list of either strftime or permalinks attributes (e.g. ["%Y', "%m"] would have year/month hierarchical indexes)

Prior Art

Jekyll

Deprecated method

https://jekyllrb.com/docs/pagination/

Activation in _config.yml:

paginate: 5
paginate_path: "/blog/page:num/" 

Quoting the page:

This will read in blog/index.html, send it each pagination page in Liquid as paginator
and write the output to blog/page:num/, where :num is the pagination page number,
starting with 2. If a site has 12 posts and specifies paginate: 5, Jekyll will write
blog/index.html with the first 5 posts, blog/page2/index.html with the next 5 posts and
blog/page3/index.html with the last 2 posts into the destination directory.

Pagination V2

https://github.com/sverrirs/jekyll-paginate-v2/

• site configuration
  • Sounds like most of this is actually defaults and can instead be set on the page:
    • "All of the configuration elements from the _config.yml file can be overwritten in the pagination pages. E.g. if you want one category page to have different permalink structure simply override the item like so"
• page configuration

Advanced sorting:

sort_field: 'author:born'

pagination trails:

pagination:
  trail: 
    before: 2 # The number of links before the current page
    after: 2  # The number of links after the current page

Gutenberg

Paginator object:
https://www.getgutenberg.io/documentation/templates/pagination/

A paginated section gets the same section variable as a normal section page. In
addition, a paginated section gets a paginator variable of the Pager type:

// How many items per page
paginate_by: Number;
// Permalink to the first page
first: String;
// Permalink to the last page
last: String;
// Permalink to the previous page, if there is one
previous: String?;
// Permalink to the next page, if there is one
next: String?;
// All pages for the current page
pages: Array<Page>;
// All pagers for this section, but with their `pages` attribute set to an empty array
pagers: Array<Pagers>;
// Which page are we on
current_index: Number;

To activate pagination on a page:
https://www.getgutenberg.io/documentation/content/section/

Tags and categories management:
https://www.getgutenberg.io/documentation/content/tags-categories/

Hugo

https://gohugo.io/templates/pagination/

In configuration:

Paginate=10
PaginatePath=page

Activation in page:

{{ $paginator := .Paginate (where .Data.Pages "Type" "post") }}
{{ template "_internal/pagination.html" . }}
{{ range $paginator.Pages }}
   {{ .Title }}
{{ end }}

or

{{ template "_internal/pagination.html" . }}
{{ range .Paginator.Pages }}
   {{ .Title }}
{{ end }}

[epage]

Had an idea on how we could handle indexing on dates. We could add a field to the paginator frontmatter that is a list of either strftime or permalinks attributes (e.g. ["%Y', "%m"] would have year/month hierarchical indexes). I've made a note in the RFC.

[epage]

Only the index_title and the extra_include points left to discuss :)

I don't know what is your idea from user point of view when you're saying:

What if instead we used Values and left it to the user? They know what they are indexing over and can make the assumption on the format of that.

So we are going to eventually support indexing over

• tag
• categories
• parts of a publication date
• taxonomies

With that, how do we handle index_title? if it is just a string then for each of those types of indexes, we will have to have a policy for how to format it. If instead it was index and the type was Value, then

• tag: index is a Value::Scalar(tag)
• categories: index is a Value::Array(categories)
• parts of a publication date: index is a Value::Array(date_parts)
• taxonomies: index depends on if we support hierarchical taxonomies or not

Since the user is making their page specific to what they are indexing on, they can easily handle the type of index being dependent on that.

[Geobert]

Yup, I had a revelation last evening and I've implemented that :D

[Geobert]

How do we let users select how much of the date to index by?

My first idea was to have that managed by the include field:

• include: Date = YYYY/MM/DD
• include: Year = YYYY only
• include: Month = YYYY/MM

but I think your idea with strfmt fields is a better idea! But maybe not in an array, as permalink cannot be an array, can it?

That gives us:

pagination:
  include: Date
  permalink: %Y/%m/%d // default value if no permalink provided?

[epage]

Except what I was talking about is not the permalink but a field for specifying what parts of the date to index over. Having to parse a permalink to guess it would be pretty complex.

[Geobert]

So, a new field?

pagination:
  include: Date
  date_index: ["%Y", "%m", "%d"]

[epage]

Something like that is what I had envisioned.

[Geobert]

To pull off the pagination on dates discussion from this giga thread, I've created #618

And I've edited first post to put some check boxes

[Geobert]

After date indexing, the missing part of this RFC is sorting by weight.
Once it's done, can we consider enabling this by default?

[epage]

Maybe? We'd need to write up the docs and do an audit to ensure this is close enough that we won't regularly break people.

[Geobert]

Ok, added doc and audit to requirements :)

[Geobert]

Ok, so I think only the audit is to be done. I don't know how we should carry this?

[epage]

Now that we're "done", it involves doing a comparison with the other solutions:

• What features do they have that we don't?
• What features did our solution give us that they don't?
• Where do we diverge in terms of approaches? Where could we converge to help people learn cobalt?

Note: normally I don't worry about this too much but this is such a big feature, that I want us to go over it again to see what we might have missed as it got broken up or as things changed.