Add `sortSidebarByLastUpdate` to blogs to change the order in the sidebar

[ilg-ul]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

When showLastUpdateTime is enabled, it also makes sense to show the updated posts in the top of the sidebar list.

Has this been requested on Canny?

No response

Motivation

When editing older posts, it is useful to give users an indication that posts have been modified recently.

API design

To control this new feature add an sortSidebarByLastUpdate option when set to true, the sidebar list is sorted by the last update time, when available.

Have you tried building it?

The functionality is implemented in cronica-it@1f21464.

Self-service

• I'd be willing to contribute this feature to Docusaurus myself.

[slorber]

What about enabling users to provide a sort function instead?

That would be more flexible and enable to sort on any attribute or frontMatter.

Also, doesn't it make sense to have the sidebar and the blog pagination be in the same order anyway?

[ilg-ul]

Also, doesn't it make sense to have the sidebar and the blog pagination be in the same order anyway?

I experimented with various conflicting solutions, and did not like any of them. My conclusion was that a single order is not enough, and I currently use two, one using the event dates and one using the last update time.

[slorber]

My conclusion was that a single order is not enough, and I currently use two, one using the event dates and one using the last update time.

You'll have to convince me and explain this in greater detail so that we can reach the same conclusion.

Please create a docusaurus.new repro with 3 blog posts including representative metadata and front matter, and the desired order (or mockups) for each component/page rendering them

[ilg-ul]

Before me taking the time to learn how to use this new tool, can we first decide if my understanding of ordering is realistic?

Assuming blog posts have the lastUpdateTime (if they don't, fallback to using the creation time):

• should the feeds be ordered by lastUpdateTime? For my site I considered this to be necessary, to allow feed subscribers to spot content changes. This also replicates the behaviour of some news sites, which show edited articles again in the feeds.
• should there be a way to show the posts in the lastUpdateTime order to the web users? For my site I considered it should, otherwise it was impossible to spot articles with updated content in the web interface. Having no other idea how to implement this, I used the sidebar to use this lastUpdateTime order, but I'm open to any other suggestions.

Assuming articles have a chronological order (by event date for blogs with historical content, with fallback to creation date for usual blogs):

• should the posts be ordered chronologically in the Archive page, grouped by years? I would say they should.
• should the posts have the next/previous links pointing to adjacent posts in this chronological order? For my site I was not sure, I implemented it like this, but I'm also considering changing the order and make these links to point to posts ordered by lastUpdateTime.

Please note that without event dates and without lastUpdateTime, these two cases collapse into one single case, using the creation date order.

[ilg-ul]

One small advice, if you allow me: when you suggest someone to use docusaurus.new, could you add a link to that site? You constantly asked me to use it, but I had no idea what it is. Only recently, while working on my fork, I bumped onto the documentation page referring to it; I totally missed it while reading the project web documentation. :-(

[slorber]

should the feeds be ordered by lastUpdateTime?

Thanks to options.createFeedItems, you can order the feeds by whatever attribute you want as long as it's in the metadata/front matter. The default feed order is the same as the order of the paginated list vue (which is already configurable (but only by ascending/descending date currently)).

function sortBlogPostsForFeed(blogPost){ {
  // Order the blog post items the way you want here
}

const feedOptions = {
        createFeedItems: async (params) => {
          const {blogPosts, defaultCreateFeedItems, ...rest} = params;
          return defaultCreateFeedItems({blogPosts: sortBlogPostsForFeed(blogPosts),...rest);
        },
};

---

should there be a way to show the posts in the lastUpdateTime order to the web users

We already have a sortPosts: 'ascending' | 'descending' option but it's limited: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog#sortPosts

If we extended it to allow a custom sort function instead of just 2 static sorting presets, you'd be able to sort by lastUpdateTime or any other metadata.

That would also impact the default order of your feed, which shouldn't be a problem considering you can change the order with the solution above if you need something different.

That would also impact the sidebar post order, which you can override through swizzle if you want to use another order.

should the posts be ordered chronologically in the Archive page, grouped by years? I would say they should.

I don't know, what else could we do anyway? It doesn't make sense to group them by last update date for example 🤷‍♂️ In any case you can swizzle this component. We group things, but you don't even have to group if you want and can keep a flat list of posts in the order you want.

should the posts have the next/previous links pointing to adjacent posts in this chronological order?

The posts are linked in the order we define thanks to the sortPosts (the one we could extend). If post2 appears after post1 in that order, then clicking "next" on post1 should lead to post2.

We don't care about the "chronology" technically, and can focus on having a consistent UX: if a paginated view has [post1, post3, post2] then the next/previous navigation button should rather keep the exact same order, no matter what this order is.

---

when you suggest someone to use docusaurus.new, could you add a link to that site?

Sorry it's GitHub refusing to autolink .new domain. I thought it was quite obvious, most users understand that it's just an URL to copy/paste in your browser.

https://docusaurus.new

It leads to a browser sandbox with a newly initialized site that you can customize, save and then share with me a runnable url easily.
I'd recommend using StackBlitz, also available at this address:
https://docusaurus.new/stackblitz-ts

This is much better for me because I'm able to run your code/attempt in isolation, on something minimal, by simply clicking a link. Running a GitHub repo is usually more time consuming.

It's also important for my own security because it's not super safe to run sites of others without double-checking there's no malicious intent to hack me in it.

When someone provides a GitHub repro, I usually first try to run in StackBlitz by adding pr.new in front of the repo url. See for example:

• Repo: https://github.com/slorber/docusaurus-starter
• StackBlitz: https://pr.new/github.com/slorber/docusaurus-starter

[ilg-ul]

... should the feeds be ordered by lastUpdateTime?
The default feed order is the same as the order of the paginated list vue

I understand that now the feed order is the same as the paginated list order, but the question was different.

I rephrase: assuming we add lastUpdateTime to the blog, and the user enables it, shouldn't the default feeds order be based on the lastUpdateTime? (without the user having to redefine the options.createFeedItems hook?).

In my opinion the feeds order should always be chronological, regardless of a possible custom order for the paginated posts (like the event dates).

---

Otherwise, if I understand you right, your solution is to add a custom sort function via sortPosts, and handle all other possible sorting orders via swizzling. It might be enough, I don't know; once implemented I'll do some experimentation to understand how complicated it gets.

[slorber]

I rephrase: assuming we add lastUpdateTime to the blog, and the user enables it, shouldn't the default feeds order be based on the lastUpdateTime? (without the user having to redefine the options.createFeedItems hook?).

I don't think it should be the case.

In my opinion the feeds order should always be chronological, regardless of a possible custom order for the paginated posts (like the event dates).

Yes, that seems a reaonable thing to do, and people can override that order anyway.

But changing that default order is a breaking change, that we can only do for Docusaurus v4.

People using sortPosts: 'ascending' will have that order too in their RSS feed (implemented in #5787). I know it's weird, and not even sure people are using this in practice, but that would be odd to change that in a minor version if anyone relies on this: they would get a totally different order by simply upgrading and probably wouldn't know about it.