Date-driven indexes

[waywardmonkeys]

I'd like to be able to have index files generated in the various year, month and day directories for my posts.

That way, visiting these pages would show the posts as one might expect:

• /posts/ -> show all
• /posts/2018/ -> show posts from 2018
• /posts/2018/01/ -> show posts from January, 2018

Is this possible with Cobalt? I didn't see anything for that in the docs.

[epage]

This isn't supported yet but I want to be able to support it. The interesting thing will be deciding how users define these.

I think Taxonomy templates are the closest thing in Hugo
https://gohugo.io/templates/taxonomy-templates/

I think this is the closest thing in Gutenberg
https://www.getgutenberg.io/documentation/content/table-of-contents/

[epage]

Other use cases besides date

• categories
• tags

Tags introduces the interesting situation of them not being ordered, so /tags/cat/awww and /tags/awww/cat probably both need to exist.

[epage]

Considerations

• How do we define the hierarchy?
• How do we define the permalink?
• How does the user access the child pages?
• How does the user access the child indexes?
• Should an index include all its immediate children pages or all descendants?
  • Could be globally configurable
  • Could be configurable in frontmatter
  • Could be differentiated by variables on the item
  • Could offer variables for both cases

Generally I've been trying to minimize configuration when it doesn't get in the way of the user getting their job done and I try to minimize duplicated information as long as it doesn't make the users job hard.

[epage]

We should also support pagination with this.

Closing #219 in favor of this because I'm guessing we won't want to support pagination generally.

[Geobert]

Once I have a first working version of my blog with current cobalt 0.11.1, I think the first feature I'll need will be pagination :) Does anyone have started this?

[epage]

No one has started this from what I've heard. The first step is gathering requirements, seeing how others handle this, and creating a proposal.

[Geobert]

On tags, usually there is no point of having multiple tags in url as they are not ordered.
Only generate url for one tag at a time. Otherwise we can end up with a combinatorial
number of pages to generate.

For categories, as they have a hierarchy, we can have multiples categories in a url, if
they are related.

For pagination some config is needed (same as Jekyll)):

paginate: 5 # nb items
paginate_path: "/page:num" # to allow path customization

these will apply to all paginations
/tags/cat/index.html and we will have /tags/cat/page2/index.html

if we want specific settings for tags or categories, we should have a way to override
defaults:

tags:
	paginate: 15 
	paginate_path: "/p:num"
	
categories:
	paginate: 20
	paginate_path: "/p:num"

For all these, no permalink, this concept is contradictory with pagination and
tags/categories.

pagination will create a paginator:
Jekyll style:
https://jekyllrb.com/docs/pagination/

or Gutenberg style:
https://www.getgutenberg.io/documentation/templates/pagination/

I don't like Hugo paginator object for some reason, maybe the hasNext field feels
bloated when a nil in prev/next is enough.

But I like Hugo generating the paginator in a lazy fashion:
https://gohugo.io/templates/pagination/

Setting Paginate to a positive value will split the list pages for the homepage,
sections and taxonomies into chunks of that size. But note that the generation of the
pagination pages for sections, taxonomies and homepage is lazy — the pages will not be
created if not referenced by a .Paginator (see below).

[epage]

Thanks for starting to look into this!

Below I explore some questions we'll need to address in coming up with this proposal

these will apply to all paginations
/tags/cat/index.html and we will have /tags/cat/page2/index.html

• How would a user tell cobalt what they are paginating on?
• It looks like you are planning on supporting mixing tags and categories?
• Can a user define precedence and if so, how? (are tags under categories or the other way)

More generally

• have you come up with a proposal for how to declare a page is an index?
• How does indexing by published_date work?

Plus my questions in my earlier post

[epage]

On tags, usually there is no point of having multiple tags in url as they are not ordered.
Only generate url for one tag at a time. Otherwise we can end up with a combinatorial
number of pages to generate.

I do see value in anding tags. I have mixed feelings about whether we should actually support it or not. If we do, I don't think we need to support it in the first release of this.

[epage]

if we want specific settings for tags or categories, we should have a way to override
defaults:

paginate_path: "/p:num"

FYI we're calling them permalinks and they use liquid templating: /p{{num}}

[Geobert]

How do we define the hierarchy?

If I got this right, categories have a hierarchy by definition:
#131 (comment)

For tags, if we want anding, maybe something simple like alphabetical order so we can
decrease the combinatorial number by two ^^'

How do we define the permalink?

It seems the paginate_path takes care of it

How does the user access the child pages?
How does the user access the child indexes?

Paginator object

Should an index include all its immediate children pages or all descendants?

Jekyll/Gutenberg gives access to immediate children, Hugo has a query language to dig deeper

Could be globally configurable

Could be configurable in frontmatter

Could be differentiated by variables on the item

Could offer variables for both cases

For the moment I've put a global conf, overridable for tags and categories

How would a user tell cobalt what they are paginating on?

For the moment, I'm thinking something like Jekyll: everything is paginated once the
configuration has been switched on.

It looks like you are planning on supporting mixing tags and categories?

I wasn't planning on this, I was thinking /tags and /categories as permalinks.

Can a user define precedence and if so, how? (are tags under categories or the other
way)

So, no, as I wasn't planning to mix them ^^

have you come up with a proposal for how to declare a page is an index?

Nope, it was a first post to see your thoughs ^^ I need to think about it, I'm not even
sure of understanding what's an index ^^'

How does indexing by published_date work?

good question, need to see how an index is build currently. What do we have as indexes at the moment?

I do see value in anding tags. I have mixed feelings about whether we should actually
support it or not. If we do, I don't think we need to support it in the first release of
this.

I see the value too, it's just the combinatorial that scares me. Maybe a config to limit
how many tags are andable at one time? With a warning on the terminal if the number is
greater than 2 tags?

[epage]

How do we define the hierarchy?

This was more about

• How do you select what you are indexing (published date, tags, category)
• If we support nested indexing, how do you define it

On a related note:

Nope, it was a first post to see your thoughs ^^ I need to think about it, I'm not even
sure of understanding what's an index ^^'

By index, I mean a page that the user writes where they intend to list out every item within the section of the hierarchy they are in.

Some systems treat the index as a special page. Other systems don't care and it can be any page.

My expectation has been that index and pagination configuration would end up living in the index's frontmatter. It could then be globally configured by setting default frontmatter fields. That doesn't mean it has to.

If every page can be an index/paginated, we'll need to watch out for how people can globally define default frontmatter for this without turning every page into an index.

It seems the paginate_path takes care of it

1. Why not just use the permalink
2. This question is meant to be more about defining the whole behavior and not just the field used.

• What are the variables and how do they behave under different situations?
• If any page can be an index, how do you differentiate between the current page's category vs the category is is a part of? Same with tags and published_date

How does the user access the child pages?
How does the user access the child indexes?

Paginator object

What does this paginator object look like? Of the ones you linked, I didn't see anything regarding child indexes. Also, how does pagination apply to child indexes? Not at all?

For the moment, I'm thinking something like Jekyll: everything is paginated once the
configuration has been switched on.

We'll want to eventually write up specifically how this applies to cobalt, particularly the fact that the jekyll paginator is no longer developed though there seems to be other paginator plugins

[Geobert]

How do you select what you are indexing (published date, tags, category)

some configuration in _cobalt?

index: [date, tags, category]

or maybe

index:
    date:
        per_page: 10
        permalink: "/{{ year }}/{{ month }}/p{{ num }}"
    tags:
        per_page: 20
        permalink: "/tags/{{ tag }}/p{{ num }}"
    categories:
        per_page: 20
        permalink: "/categories/{{ categories }}/p{{ num }}"

where categories are defined like in #131

so we'll have /categories/MainCat1/SubCat1/p{{ num }}, /categories/MainCat1/SubCat2/p{{ num }}, /categories/MainCat2/SubCat3/p{{ num }}…

If we support nested indexing, how do you define it

Nested? Now that I understand what an index is, what do you mean by nesting them?
An index listing by date that include another .liquid file that is an index listing on
tags for exemple?

My expectation has been that index and pagination configuration would end up living in
the index's frontmatter. It could then be globally configured by setting default
frontmatter fields. That doesn't mean it has to.

So a page will be an index if it has index/pagination configuration in its frontmatter?
But in this case, how the global config will behave?

What are the variables and how do they behave under different situations? If any page
can be an index, how do you differentiate between the current page's category vs the
category is is a part of? Same with tags and published_date
What does this paginator object look like? Of the ones you linked, I didn't see anything
regarding child indexes. Also, how does pagination apply to child indexes? Not at all?

paginator.date.posts : all posts ordered by dates
paginator.date.next_page/prev_page : permalink to next/prev page

paginator.date.[year].posts : all posts for year
paginator.date.[year].next_page/prev_page

paginator.date.[year][month] : all posts for month
paginator.date.[year][month].next_page/prev_page

paginator.tags.[tag].posts : all posts for tag
paginator.tags.[tag1][tag2].posts : all posts that have both tag1 and tag2
paginator.tags.[tag].next_page/prev_page
paginator.tags._all : all the tags

I don't know if [tag1][tag2] is feasible or not but this is a first try :)

[epage]

Thanks for continuing to look into this!

Could you collect all of your thoughts into an RFC issue so we can see how all of the pieces fit together?

[Geobert]

What's an RFC issue?

[epage]

Basically open an issue that is just us planning this feature. The issue will be the proposal and we'll edit it as we refine the idea.

Kind of like what I've been doing with #301 and other planning issues.

[Geobert]

At least, catched some time to do this #395 ^^

[Geobert]

Shall we close this and do it in #395 ?

[epage]

Yeah, seems like we could close this for #395.