feat(blog): allow sorting blog posts through a options.sortPosts function hook

[OzakIOne]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

Allow the user to pass a function to sort blog posts, until now, users only had the choice between ascending and descending sorting options, we want to provide to the user the possibility to pass a function which enable other sorting order

Todo:

• check for invalid preset ? check if typescript already protects for this, otherwise create a getPreset function
• move presets outside of function
• put a type for the map input enum output sort function
• put blogpost as params for preset, presets should have the same signature of the sort function,
  record ascending descending to blogpost sort preset, call sort function like preset function
• dogfooding test

Test Plan

Test links

Deploy preview: https://deploy-preview-9840--docusaurus-2.netlify.app/

Related issues/PRs

#9831

#5787

#5692

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 69	🟢 98	🟢 96	🟢 100	🟠 88	Report
/docs/installation	🟠 89	🟢 96	🟢 100	🟢 100	🟠 88	Report
/docs/category/getting-started	🟠 75	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog	🟠 67	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 60	🟢 96	🟢 100	🟢 100	🟠 88	Report
/blog/tags/release	🟠 71	🟢 100	🟢 100	🟠 80	🟠 88	Report
/blog/tags	🟠 76	🟢 100	🟢 100	🟢 90	🟠 88	Report

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	c949c3f
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/65d8b81913407600085c4278
😎 Deploy Preview	https://deploy-preview-9840--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[slorber]

Test this by applying this to the dogfood blog plugin.

For example you can write a blog post with an old date, and make it appear in 1st position thanks to a front matter field?

[slorber]

Your presets sort blog posts imperatively and do not return a list of blog posts. IE when using presets the returned value is undefined.

I'd prefer if this function consistently returned a list of sorted blog post. If the input list is mutated without creating a copy, you'd rather return it.

[slorber]

We need good unit-test coverage of this function, covering both mutation modes, with all possible combinations

• usage of a preset
• usage of imperative mutation sort function (sort the input list, return undefined)
• usage of fp mutation sort function (return a sorted blog post list copy)
• undefined sort function

---

What about another helper function that resolves preset names to their respective sort functions?

function getSortFunction(sortPosts: Options["sortPosts"]): SortBlogPostsFn {
  if (typeof sortPosts === 'function') {
    return sortPosts
  }
  if (typeof sortPosts === "string") {
   const presetFn = presets[sortPosts];
   if (!presetFn) {
     throw new Error("sortPosts preset "+sortPosts+" does not exist");
   }
   return presetFn;
  }
  // a sort function that does nothing and keeps the initial order
  return () => {};
}

[slorber]

Suggested change

// TODO document this type

We don't document the BlogPost type yet, cf CreateFeedItemsFn above.

We probably should but I'd consider it's not the responsibility of this PR to add this doc, because we need to think a bit about the public API surface we want to expose/document here.

We'll probably document this later but maybe not all the fields, because we don't necessarily want to lose the ability to rename/remove attributes (cf the formattedDate that we'd like to remove).

For now this is kind of undocumented on purpose, so that we consider it's not public API and we can still refactor in v3.x without considering it as a breaking change.

[slorber]

remove TODO for now

[slorber]

Suggested change

	((args: {blogPosts: BlogPost[]}) => void | BlogPost[])
	type SortBlogPostsFn = (params: {blogPosts: BlogPost[]}) => void | BlogPost[]

Follow the declaration convention of type params above: give a name to type and use params instead of args (also in code if possible)

[slorber]

Maybe extending sortPosts is not the API we want, and instead, it would be better to directly implement a processBlogPosts() hook (or any other name?).

Technically it would do the same, but the name would be broader, not limited to sorting.

What do you think @OzakIOne @Josh-Cena @ilg-ul ?

The way I see it, the existing sortPosts preset option would be applied earlier because it's less powerful.

let blogPosts = await loadBlogPosts();
blogPosts = applySortPreset(blogPosts,options.sortPosts); 
blogPosts = applyProcessing(blogPosts,options.processBlogPosts); 
// ...

Eventually we could later deprecated options.sortPosts considering you can already sort posts with options.processBlogPosts

[slorber]

too verbose test code, create a helper that can accept partial blog post args and let us focus on what matters

Your test should be as readable as this (pseudo code), with the intent being super clear

it("sorts descending by default",() => {
  const blogPost2022 = createBlogPost({date: new Date('2022-12-14')});
	const blogPost2023 = createBlogPost({date: new Date('2023-12-14')});
	const blogPost2024 = createBlogPost({date: new Date('2024-12-14')});

  assert(sort([
	  blogPost2022,
	  blogPost2024,
	  blogPost2023,
  ])).equals([
		blogPost2024,
		blogPost2023,
		blogPost2022
	])
});

It's preferable if each test create its own inputs, instead of relying on a shared list of posts for all tests. As we add tests, this list will only grow over time and tests will become harder to understand and maintain

[slorber]

remove TODO for now

[slorber]

I'm not sure why someone would return an empty array by mistakes.

Users are likely to either return undefined, or return a new sorted list of posts.

If we want to prevent mistakes, we should check that blogPosts.length === sortedBlogPosts.length.

We could check that the returned value is an array, because users might use JS in config files and return an unsafe value such as a number 🤷‍♂️

---

But I'm not sure we want to prevent that anyway, because sortPosts could also be used as a temporary workaround to filter/modify posts until we come up with a better API for it.
It's not the primary use case of this API, and it's a bit awkward to do so.
See my comment here:
#9846 (comment)

Maybe sortPosts is not the API we should extend?

[ilg-ul]

it would be better to directly implement a processBlogPosts() hook (or any other name?)

Or even use the more generic afterContentLoaded(), as suggested in #9863?

[slorber]

it would be better to directly implement a processBlogPosts() hook (or any other name?)

Or even use the more generic afterContentLoaded(), as suggested in #9863?

I've thought about it, and it's a potentially good flexible low-level solution, but we are not ready for it and it's much more complicated to implement.

Notably, the blog post content historically has this shape:

  export type BlogContent = {
    blogSidebarTitle: string;
    blogPosts: BlogPost[];
    blogListPaginated: BlogPaginated[];
    blogTags: BlogTags;
    blogTagsListPath: string;
  };

You will notice that the loaded content is "already paginated". If you apply content.blogPosts.sort(...) after content loading, the order you define will not impact the paginated display order, which is unexpected.

So, for now, I'd prefer to focus on a convenient high-level feature to sort/filter/modify blog posts through plugin options, rather than a generic plugin solution to do the same on plugin-loaded content. I'd still like to make this generic solution possible in the long term but it's challenging and I'm not sure how yet.

[slorber]

Closing in favor of #9886