Enhance support for posts related to events in the past

[ilg-ul]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

Add new front matter metadata to define the actual event date, and update the sorting logic to order pages by event date, when available.

With this new logic, the Archive page would look something like this:

Has this been requested on Canny?

No

Motivation

The common use case for blogs is to document recent events; in other words, the post date and the event date are more or less the same.

For blogs documenting historical events, the post date remains in the present, as for regular posts, but the event date is in the past, and can be entered as a separate frontMatter string property.

API design

Since some historical events do not have an exact date, this property can be incomplete, without day or even without month, for example:

event_date: '1994'
event_date: '1994-11'
event_date: '1994-11-07'

For events that lasted more than one day, it is possible to also define the end date, as a string with the similar incomplete syntax:

event_end_date: '1995'
event_end_date: '1994-12'
event_end_date: '1994-11-08'

To control this new feature add a sortPostsByEventDate option; when set to true, the event dates are parsed and used when sorting the posts in the Archive page, so the years of past events are located at the end.

Have you tried building it?

The functionality is implemented in cronica-it@eb1a24e.

Self-service

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

[slorber]

I'd prefer to not implement the concept of "event" in the blog plugin: this is proprietary logic of your site.

However, we could provide you primitives and hooks to sort and re-order the blog posts for all views (pagination, archive, sidebar...) according to your custom front matter. This is more flexible and unlocks other fancy use cases as well.

Also suggested in #9827

If you only want to re-order the content of the archive page (and not other views), I'd suggest to swizzle and sort directly inside the appropriate React component, using your custom metadata at post.metadata.frontMatter.event_date

[ilg-ul]

However, we could provide you primitives and hooks to sort and re-order the blog posts for all views

If such a solution will be implemented, I'll reevaluate.

I tried swizzling and ordering inside components, but faced difficulties, for example I thought that the next/previous links in each posts should link to articles ordered by in the event date, not the post creation or even post last update, while the posts in the feeds need to use the last update time.

The second attempt was to write a separate plugin, but the solution got too complex due to dependencies with other plug-ins.

Thus in the end I forked and experimented with all these changes.

If you think a similar functionality can be obtained with hooks, sure, but there will probably be more, for example the formatted date in the Archive page also needs to use the event_date/event_end_date, when available.

[slorber]

I tried swizzling and ordering inside components, but faced difficulties

Swizzling to re-order items will only work for non-paginated lists, such as the archive page and the sidebar list.

I thought that the next/previous links in each posts should link to articles ordered by in the event date, not the post creation

Next/previous linking is done based on the order of the posts, so if we let you sort them before doing this navigation linking based on your custom attributes, the linking will be consistent with the display order of the paginated lists

the posts in the feeds need to use the last update time.

You can define a custom order for the RSS feed thanks to createFeedItem()

---

If you created me a runnable minimal docusaurus.new repro using only a few blog posts and a clear specification for what each screen/component/feed should render, I would be able to show you a solution, or at least understand better the missing primitives to implement.

[ilg-ul]

Since you do not plan to include this functionality as-is, I suggest to leave this proposal at the end, and focus on features you already agreed to include.

However, when adjusting the design for the other features, we should keep in mind that there might be use cases when custom front matter properties will be used, which will affect the order of the posts and the logic to format dates in some components (like the Archive page).

[slorber]

Since you do not plan to include this functionality as-is, I suggest to leave this proposal at the end, and focus on features you already agreed to include.

Agree 👍

However, when adjusting the design for the other features, we should keep in mind that there might be use cases when custom front matter properties will be used, which will affect the order of the posts

I'm pretty sure once we extend sortPosts to allow functions you'd be able to achieve your needs, but for that, we'll have to iterate on a https://docusaurus.new repro to be sure.

and the logic to format dates in some components (like the Archive page).

the logic to format dates should be overriden with swizzle

---

Let me know if there are features you want to work on in priority. I'd like to give some of them to my intern.

[ilg-ul]

Let me know if there are features you want to work on in priority. I'd like to give some of them to my intern.

I'm in no hurry, you can give all of them to your intern, just add me to the discussion to keep track of the progress.

Probably the Authors feature should require some extra attention.

[ilg-ul]

Thank you!

We're getting close, two more to go, a minor one #9829 and the Authors pages #9825, plus the pending PR #9912 for LastUpdateTime.

When all will be completed, I'll try to rework my sites with historical data.

[slorber]

👍 we'll try to fix those soon