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.

[ghost]

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?

[ghost]

Thanks @slorber. Alphabetical order was just an example — really I just mean, like the others said, that it'd be nice to have more natural control over the ordering.

I considered using docs or pages, and I think those could work fine. There are just slight feature differences between them, so I tried to pick the best fit that wouldn't require lots of swizzling (which the documentation pretty strongly warns against doing) and the blog option seemed the best

[factoidforrest]

If you could put a position: 3 tag in the frontmatter of a blog post, that would solve our need for this.

[slorber]

If you could put a position: 3 tag in the frontmatter of a blog post, that would solve our need for this.

@factoidforrest can you explain the use-case for this? What concrete problem are you trying to solve?

[cerkiewny]

Also if you could explain how it would work with combination with sorting? Would that override the sorting and shuffle something in always at position 3? Would you need to specify order of all items in that case? Do you want to just make sure that some items are first in the order? @factoidforrest

[factoidforrest]

@slorber Well, we sometimes produce multiple blog posts per day, and it would be nice to individually control their position.

Or sometimes we have something REALLY important and we want to stick it to the top. We recently did the blog post about log4shell which is why this is coming up. https://www.lunasec.io/docs/blog/log4j-zero-day/

@cerkiewny I think that's all open to debate, but if you want to see a project with inspiring document sorting (that works with docusaurus), you can check out typedoc https://typedoc.org/guides/options/#sort

For the manual position override, the way I would write the code is:

1. Sort by date, which is the lowest priority and default sort
2. Take the output of 1 and sort by position if present, honoring the above order otherwise.

That way people can manually move things around when they need to, but still keep the default behavior most of the time.

[slorber]

@factoidforrest

Well, we sometimes produce multiple blog posts per day, and it would be nice to individually control their position.

In this case, you can use the date frontmatter to specify a time: date: 2021-12-20T10:00:00Z

Or sometimes we have something REALLY important and we want to stick it to the top. We recently did the blog post about log4shell which is why this is coming up. lunasec.io/docs/blog/log4j-zero-day

Would you use position: 3 for such a post?

IMHO what we are looking for here is rather a way to "pin" a blog post at the top (similar to GitHub issues somehow).

It's also a common pattern among bloggers to have featured posts, and drive more attention to specific articles:

• https://leerob.io/
• https://www.joshwcomeau.com/
• https://blog.maximeheckel.com/

We could allow a plugin option to feature a list of posts, put them at the top, and maybe also add them to the blog sidebar to make them accessible from all blog pages.

Using featured: true frontmatter can also be nice, but not sure how to ensure an order in this case though

---

Using something like position: number is quite ambiguous, particularly when not all items have an explicit position, and we can't prevent users to use the same position twice. + when adding a new blog post, do you really want to edit and offset all previously defined positions 😅

If this position is only applied inside a single day, it would be a quite unintuitive option, and using an hour in frontmatter can be enough.

[homotechsual]

So I've hit a need for this where we have multiple posts on the same day which aren't ordering correctly. There are a few options that would help - allow the date sorting to support date/time. Or allow weight.

I'm aware position has been discussed - weight in my eyes is different. Position is "absolute" whereas weight nudges within the existing sort criteria - lighter items float, heavier ones sink. So two posts with the same dates - their final order would be determined by their weight.

I can also see real benefit in featured as a boolean prop.

[Josh-Cena]

@homotechsual featured is certainly useful, you can submit a casual feature request for that so it's on our tracker. About ordering posts on the same day, little known is that the front matter date is more powerful than filename date, because the former supports datetime syntax. In fact, our changelog uses it to order multiple versions published on the same day:

---
date: 2019-06-07T20:00
---

[homotechsual]

This is beautiful information, I'll raise a PR for the API docs to make it clearer that this handles datetime :-) thanks!

As for featured - I'll get an FR in for that!

[slorber]

Is anyone using custom sorting logic (ie "ascending"?)

Do you expect the RSS feed to be in ascending order too? 🤔

Asking for #9827 (comment)

We are looking to implement a sort function config (#9840) but it's not clear how this should impact the order of the RSS feed.

I feel that the order of the feed should rather be chronological (descending) by default in any case, but that's not how the sortPosts feature was initially implemented so changing this now is a breaking change.

I never met anyone using this feature in practice so I'm not sure what users expect. Is anyone even using this feature? 😅

[homotechsual]

Not using custom ordering at present but agree that the RSS feed should maintain chronological ordering but perhaps be configurable separately from the display ordering.

[ilg-ul]

Is anyone using custom sorting logic

Such custom logic is proposed for sites with historical posts, tagged with past event dates:

• Enhance support for posts related to events in the past #9831

One example of such site is:

• https://cronica-it.github.io/evenimente/arhiva/

I feel that the order of the feed should rather be chronological (descending) by default in any case

Fully agree. The feed order should be decoupled from the post order.

And if the blog posts will be enhanced to support lastUpdateTime (#9826), my preference is to order the feeds by lastUpdateTime too.

[slorber]

And if the blog posts will be enhanced to support lastUpdateTime (#9826), my preference is to order the feeds by lastUpdateTime too.

I don't think this one is a reasonable default.

Many blogs have last update time and keep their feed in chronological order.

As a curator myself and heavy RSS user through my newsletter (https://thisweekinreact.com), I really dislike when authors order their feed by last update date, because it notifies me of changes I'm not interested to know about.

By chance, it doesn't happen often.

[mhowes-veracode]

We use a blog for our product updates/release notes, with a separate Markdown file for each product. We use the RSS feature, which involves changing the date in the front matter to trigger RSS and this date change moves the file with the latest date to the top of the list. We use a "landing page", which we would like to pin to the top, that explains this behavior to the user: https://docs.veracode.com/updates/r/c_release_notes

Is it possible to prevent files with the latest date from moving to the top of the list?

[slorber]

@mhowes-veracode we have features to give you full control:

• in v3.2 the blog has a new processBlogPosts option allowing you to sort the posts and put your "landing page blog post" at the beginning/top if you want that. Although technically you could also swizzle the paginated blog list component and render your "landing page" here, not necessarily as a blog post, but as a regular React component (it could be a MDX partial, more convenient)
• we have a createFeedItems allowing you to do the same for the RSS feed. You can decide which item appears first in the feed, using custom logic and custom front matter fields if you want to.