Blog posts page: custom sorting logic

[Josh-Cena]

🚀 Feature

Let's be less opinionated and let users decide on the sorting logic.

Have you read the Contributing Guidelines on issues?

Yes

Has this been requested on Canny?

Requested on Discord

Motivation

Sorting by descending time works in almost all cases, but we shouldn't assume that all users use the blog for time-based information. E.g., sort by alphabetical order? Sort by tags?

API Design

A new comparePosts plugin option, which accepts a function that is passed to the sorting algorithm:

docusaurus/packages/docusaurus-plugin-content-blog/src/blogUtils.ts

Lines 345 to 347 in b40e459

	blogPosts.sort(
	(a, b) => b.metadata.date.getTime() - a.metadata.date.getTime(),
	);

And yes, it will receive the entire blog post, with all of its metadata and content.

Have you tried building it?

No; should be trivial

[slorber]

Yes we can add that option.

Just curious if someone came up with more concrete needs?
Who wants to order by alphabetical/tags and why exactly?
Are we adding an option just for the sake of adding it or will nobody use it in practice?

Does it mean that we'll never add something like a "year separator" in the paginated view?
Some UX patterns may only make sense for descending order.

[Josh-Cena]

This has been requested two / three times on Discord but... they didn't provide a use-case🤦‍♂️

I was just dumping all sane feature requests that I saw on Discord :P

Does it mean that we'll never add something like a "year separator" in the paginated view?

If that's actually on the roadmap (I never saw a feature request for that anyways), then yeah, it won't make much sense otherwise.

One use-case I can think of is the blog plugin being used for more general-purpose content posting, like Trello or as an online wiki🤪

[slorber]

I'd like to create a plugin for myself to create a digital garden / second brain / Zettelkasken / Obsidian / Roam Research / whatever you name it for interconnected thoughts and public note-taking.

I'm not sure it makes sense to try to adapt the blog plugin to this use-case, maybe a new separate plugin could be a better idea?

[cerkiewny]

Do you see the option here more as some enumerated option (alphabetic/chrono etc.) or rather the lambda for sorting function should be provided?

[Josh-Cena]

Do you see the option here more as some enumerated option (alphabetic/chrono etc.) or rather the lambda for sorting function should be provided?

As a function. We are providing an API anyways, and by Sebastien's philosophy we should make it as general-purpose as possible.

[Josh-Cena]

@cerkiewny This is the FR that I would actually think twice before rushing to implement. It's trivial to add, but is it really worth it? I'm only putting it up for RFC purposes and to remind myself that there's a possible feature, but overall I don't see a strong use-case and I agree with @slorber that this may hinder us from building features that assume chronological ordering of posts and that other use-cases of the blog can be realized with another plugin

[Josh-Cena]

Also, these days I'm not really a fan of having heavyweight callbacks as API just for more freedom of customization🤷‍♂️ This applies to sidebarItemsGenerator, readingTime, etc. I once had a crazy idea of reading .docusaurusrc in JSON format, maybe even YAML, but realized all these non-serializable APIs make that impossible

[cerkiewny]

I don't think it is quite as easy to add as another plugin, you have the contextual "next" and "previous" generation for the blog posts, which would be really awkward if they were sorted differently to the plugin sorting. I don't have strong feelings about this feature, and I would personally add something looking more like enum:

{
  blogSorting: chronologicalDesc // also would have few more options like chronologicalAsc, maybe alphabeticalDesc/alphabeticalAsc
}

My feeling is that the only strong use case here is reversing the order from oldest to newest

[slorber]

Agree, we should rather just provide a way to reverse the order for now, but think about keeping the API extensible just in case.

blogSorting does not seem like an ideal name.

What about orderBy: "date-descending".

That would match the name of the widely used Lodash orderBy (https://lodash.com/docs/#orderBy) and we could later eventually provide other presets and multi-criteria ordering.

Note we have a date frontmatter so it seems nice to keep this name too.

I can add my vote here. I've been trying to find a way to do this because I'm using the blog part of the site as a personal portfolio. The sidebar list is especially useful for that purpose (though I wish it were more fully featured / adjustable like the docs one) except that I can't sort by anything.

I'd like to be able to do alphabetical, and I'd love love to let people filter by tags. I've tried swizzling the and similar components to do something like this but honestly it's too hacky.

[slorber]

@certainlyNotHeisenberg about displaying the tags in sidebar, check this issue: #5461

It's not clear to me what you want to use the blog with an alphabetical order. Why not use docs or regular pages for your portfolio?