How to customise code outside the components listed by swizzle? (like blogUtils.ts)

[ilg-ul]

I'm trying to customise docusaurus-plugin-content-blog, to accommodate a chronology, where posts, in addition to the creation date, also have a separate event date.

Since docusaurus currently processes only a single date, I stored the event date in frontmatter.date, and the creation date as frontmatter.creationDate. This is generally fine, I see the events grouped by actual dates in the archive pages, but it has some disadvantages, like not knowing when the posts were created and the rss.xml not listing the most recent posts.

One possible fix would be to customise the feed generation (which does not seem trivial, at least I could not find a way to swizzle it).

Another fix would be to revert to using frontmatter.date for the creation date, and a separate frontmatter.eventDate.

However this requires some customisations in blogUtils.ts, where I have to also create lists of posts sorted by event date.

I managed to swizzle some components, but I could not find a convenient way to customise blogUtils.ts, and forking the entire plug-in is not very attractive since it adds a significant maintenance cost.

My application may not be very common, but raises an issue which might be helpful for others, which is a generic mechanism to customise code outside the components listed by swizzle.

Is there such a mechanism? If not, would it be worth designing one?

[slorber]

Show me a runnable example of your attempt.
Show me mockups of what your goal is in terms of UX for all the pages you need to implement.

A wall of text is not super helpful and I might not interpret it well.

Links you might be interested in:

• Extend existing content plugins (CMS integration, middleware, doc gen...) #4138
• https://docusaurus.io/blog/releases/2.3#blog-createfeeditems
• https://docusaurus.io/blog/releases/3.1#parsefrontmatter-hook

[ilg-ul]

Show me a runnable example of your attempt.

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

and the home page:

• https://cronica-it.github.io/preview/

The text is in Romanian, but for French speaking people it shouldn't be that hard to figure out (Cronica -> Chronique, Evenimente -> Evènements, Arhiva -> Archive, Categorii -> Catégories, Amintiri -> Mémoires/Témoignages)

The site is a dual blog, with a chronology of dated events and a collection of dated memories.

Show me mockups of what your goal is in terms of UX for all the pages you need to implement.

The UI is almost unchanged, I only swizzled the theme/BlogArchivePage to remove the date, the rest is unchanged.

The site is generally ok, except some small details, for example the post date, which is way in the past, at the event date:

This happens because I had to use the date property as event date:

---
slug: 1969/calculatorul-iris-50
title: 'În Franța, compania CII anunță calculatorul „Iris 50”'
authors: [ilg-ul]
tags: [autor:liviu.ionescu]
date: 1969-07

creationDate: 2024-01-08T17:01:55

eventDate: '1969'

---

Please note that chronologies may have vague event dates, like a single year, or a month in an year (no day)'; however the date: property is parsed by the JavaScript code, and must include a month, in this case I used 1969-07, and the displayed date resulted as July 1st, 1969, which is not ok.

My preferred solution would be to leave the date property to store the creation date, and use the custom eventDate to sort the posts.

For the feed.xml, if I understood your links right, I think I can customise the logic to select the most recent posts, even if I manage to reorder the posts by event dates.

So, if you prefer a specific question to a specific issue, it is how to customise the post sorting order to use a custom logic?

My current poor understanding of the code is that for some specific functions there are callbacks. A more generic question would be whether a more universal customisation mechanism can be invented, to allow customisations in any parts of the glue code not only in the components via swizzle.

An example of such a solution would be use class instances, and allow the user to create custom instances that extends the existing functionality.

But this might be too much, in my case any solution that allows me to customise the blog posts order would be fine.

[slorber]

The site is generally ok, except some small details, for example the post date, which is way in the past, at the event date:

You can swizzle that component and render another front matter date (or plain string) if you want to.

Please note that chronologies may have vague event dates, like a single year, or a month in an year (no day)'; however the date: property is parsed by the JavaScript code, and must include a month, in this case I used 1969-07, and the displayed date resulted as July 1st, 1969, which is not ok.

The date is what drives the blog post pagination ordering and the initial feed order (that you can alter with createFeedItems)

It doesn't mean that technically you have to display that date. You can swizzle all components and display another custom front matter field if you want.

So, if you prefer a specific question to a specific issue, it is how to customise the post sorting order to use a custom logic?

We don't provide this ATM. What is the problem with ordering by date considering you don't have to display that date?

Even if you have events like "April 1969" or "1969 year", at some point you have to be explicit and tell Docusaurus which one should appear first in the list, so giving us an explicit instant in time permits to create a predictible order.

My current poor understanding of the code is that for some specific functions there are callbacks. A more generic question would be whether a more universal customisation mechanism can be invented, to allow customisations in any parts of the glue code not only in the components via swizzle.

We already implement a plugin system, and you can copy/paste our blog plugin and adapt it to your needs if needed. Note that the blog plugin is not a chronology plugin. I'm ok to consider extension points but I'm not convinced what you want is needed for regular users that want to implement a blog, unless you prove otherwise.

---

To proceed further, I'd kindly ask you to put your time in to create a minimal repro and mockups of your desired outcome, otherwise we are losing time with walls of texts and no concrete solution. A link to your prod site is convenient for you, but not for me.

Please:

• create a docusaurus.new sandbox with 3 or more blog posts being representative of your system
• use excalidraw.com to draw a page mockup of what you want as the outcome of the Docusaurus build (one mockup per page)

Only then I'll be able to tweak your runnable sandbox and adapt it to fit your need, by giving you actual code instead of writing words.

[ilg-ul]

As requested, I created:

• https://github.com/ilg-ul/docusaurus-9716

There is no need for mockup pages, the existing ones look fine.

The question is how to customise the blog plugin to sort the posts in the Archive page and the posts below specific Tags, to use the frontmatter.eventDate property instead of date: (like this page).

The content of eventDate is a string that may look like

• YYYY (for sorting purposes equivalent of YYYY-07-01, but displayed only as YYYY)
• YYYY-MM (for sorting purposes equivalent of YYYY-MM-15, but displayed as month-name YYYY)
• YYYY-MM-DD, displayed as usual.

The logic to process the custom frontmatter properties probably can be accommodated by the parsefrontmatter-hook, but I could not find a solution to customise the sorting order.

[slorber]

The question is how to customise the blog plugin to sort the posts in the Archive page

You can swizzle the blog archive page and modify the order. Normally you can access custom front matter on the list this page receives.

There's also a blogArchiveComponent that lets you provide your own theme component to implement this page from scratch.

https://docusaurus.io/docs/3.0.1/api/plugins/@docusaurus/plugin-content-blog#blogArchiveComponent

Just sort the blog post array based on blogPost.metadata.frontMatter.eventDate if you want to, that's UI logic you can customize and implement yourself

---

If only you provided a docusaurus.new minimal repro following my exact instructions, including only 3 markdown files (not containing romanian), mockups for each blog page you care about showing blog posts and their appropriate displayed date, and feed order you want, I would give you the solution by forking your sandbox, coding 5 minutes in it, and we would all save time.

[ilg-ul]

You can swizzle the blog archive page and modify the order. Normally you can access custom front matter on the list this page receives.

Right, I did this and the Archive page is now ordered by eventDate. :-)

The code to do this is:

https://github.com/ilg-ul/docusaurus-9716/blob/5d577932195ec1b114554633925bc877d57f2d89/website/src/theme/BlogArchivePage/index.js#L48-L59

However I do not find a similar solution to reorder the posts in the Tags pages.

For example the /blog/tags/docusaurus has a few posts, listed in the date order, and they should be ordered by eventDate.

If only you provided a docusaurus.new minimal repro following my exact instructions, .., mockups for each blog page you care about showing blog posts and their appropriate displayed date ...

Sorry, but I simply do not understand what mockups I have to provide, since I do not need to change anything in the layout of the pages, I just need to show exactly the same information, but with the posts ordered by frontMatter.eventDateISO (a value computed in the frontMatter hook from the user provided eventDate).

• https://github.com/ilg-ul/docusaurus-9716/blob/5d577932195ec1b114554633925bc877d57f2d89/website/src/utils/frontMatterEventDates.ts#L31

The project is minimal, I removed all my posts and added the eventDate property to your default posts.

The /blog/archive page is ok now, it shows the past events, properly ordered.

If we can find a solution to reorder the posts below /blog/tags (for example in /blog/tags/docusaurus), to be in the same order as shown in Archive, the problem is solved.

The order is:

[ilg-ul]

I tried to swizzle BlogTagsPostPage, but the parameters it receives (items) do not seem to include the post frontmatter, so reordering them is not as easy as for the Archive page. :-(

[slorber]

Sorry, but I simply do not understand what mockups I have to provide

I'm sorry but you don't follow my rules so this will be my final answer

The project is minimal, I removed all my posts and added the eventDate property to your default posts.

No it's not minimal, it contains many blog posts, still use Romanian, and I can't run/modify it in a blink like I would with docusaurus.new

What I'm asking you is a clear minimal content input such as:

# ./blog/event-1.md
---
someFrontMatter: XYZ 
---

# Event 1

# ./blog/event-2.md
---
someFrontMatter: XYZ 
---

# Event 2

# ./blog/event-3.md
---
someFrontMatter: XYZ 
---

# Event 3

And a clear mockup output (for each page) such as:

Only when I have a clear minimal content input, and what is the expected visual ouput of all the pages, I can help you implement the thing.

Not providing this puts the burden on me to invest time, re-read again your walls of texts again and again to attempt map your text to a mockup in my head, and figure out if we are still on the same page everytime as the discussion evolves.

For this reason, again, I'm going to stop helping you unless you do exactly what I ask for. This is not time well-spent from my perspective.

---

My last answer until minimal runnable repro + mockups are provided:

I tried to swizzle BlogTagsPostPage, but the parameters it receives (items) do not seem to include the post frontmatter, so reordering them is not as easy as for the Archive page. :-(

BlogTagsPostsPage items do receive the front matter.