Blog posts should be able to display last update date

ZhymabekRoman commented 1 year ago

Have you read the Contributing Guidelines on issues?

[X] I have read the Contributing Guidelines on issues.

Description

Implement blog page last updated time.

Has this been requested on Canny?

No response

Motivation

Blog like a docs require updates, may be typo fixes, or often API changes of product for examples, or some new announcements

API design

Like a PR for docs: https://github.com/facebook/docusaurus/pull/7461

Have you tried building it?

No response

Self-service

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

johnnyreilly commented 1 year ago

I think you're asking for something different, but I wanted to check if either of these approaches addresses your needs?

Both of the above relate to sitemaps / rss - I suspect that's not what you're after but I thought I'd ask

hametGh commented 1 year ago

I'd be happy to work on it. As it's already in Docs, it'll be easy to add it to blogs, and it'll help me learn the code so I can start contributing

ZhymabekRoman commented 1 year ago

I'd be happy to work on it. As it's already in Docs, it'll be easy to add it to blogs, and it'll help me learn the code so I can start contributing

Just do it!

slorber commented 1 year ago

So what I understand is that you want all this but for blog posts?

CleanShot 2023-02-16 at 17 59 52@2x

It's important to understand if there's a strong use case to introduce this new feature.

Is this something that you actually need in practice for a concrete use case, or simply an improvement that you imagined would be useful but don't particularly plan to immediately use it?

Do you have any real/production live blog post URL to share, on which you'd like to show this new last update data?

ZhymabekRoman commented 1 year ago

So what I understand is that you want all this but for blog posts?

Yes

Is this something that you actually need in practice for a concrete use case, or simply an improvement that you imagined would be useful but don't particularly plan to immediately use it?

Do you have any real/production live blog post URL to share, on which you'd like to show this new last update data?

Why isn't this feature useful? This could be a company blog, not necessarily mine or anyone else's. Personally, I'm willing to use this functionality on my own site because I want visitors to know that the article has undergone a change after publication due to a new version of the library or something like that. And why should I answer this question in the first place? If this functionality is available in the documentation pages, why not ask yourself why this functionality is in the documentation? We are not perfect, we are not blamelessly wrong. We learn from our mistakes.

slorber commented 1 year ago

@ZhymabekRoman we try to only build features that people will actually use in practice. If people just come up with "ideas" and don't plan to use them in practice, is this actually useful to build it in the first place? I ask similar questions in almost all feature requests, not just this one.

And why should I answer this question in the first place? If this functionality is available in the documentation pages, why not ask yourself why this functionality is in the documentation?

Not sure why you take it that way, I just kindly ask you to play the game of describing your use case so that we figure out if it's worth it to implement, and eventually get insight on how to design it best. I'm not saying this feature is not useful, I'm just saying I'd like to know more. Ideally, we'd like to have multiple users say "I plan to use this feature because [reasojn]" before implementing it, so that we can implement something that works for all users asking for this feature.

Now as it's already on the docs plugin, that seems reasonable to be consistent and add this to the blog plugin too, but there are certainly some subtilities to handle for this specific case that we could discuss first.

We are not perfect, we are not blamelessly wrong. We learn from our mistakes.

I have no idea what you mean here sorry 😅

Personally, I'm willing to use this functionality on my own site

Is this the blog you plan to use this on? https://zhymabekroman.github.io/blog/posts

because I want visitors to know that the article has undergone a change after publication due to a new version of the library or something like that.

Did you already have the use case on your blog? I only see one post in the link above, would it be important to show that edit date?

Wouldn't it be better to use your own words to describe why the blog post has been edited instead of just showing an author/date at the bottom?

Do you plan to use Git edit date for that or explicit frontMatter?

Again, I'd like you to be very concrete. If you want an edit date to appear on a specific blog post, please share the URL, and explain why you want the edit date to appear.

For example:

I want the edit date to appear on blog post [url] in a similar way it does for docs because [reason]. I plan to provide this edit date through [git history | frontMatter]. Using custom text in the blog post intro is not a good workaround because [reason]...

Questions to be answered:

Is displaying the editing author actually useful? Unlike docs, blog posts have a list of authors at the top.
Should the edit date appear on the paginated list? (the list view does not exist for docs but does for blog posts)
Should this impact SEO meta tags or sitemap? probably
Should this impact the RSS feed order?

I hope you understand better why I ask all those questions now.

The goal is not to rush into implementing an idea but to collect community feedback before implementing this so that we implement it the right way.

TheCatLady commented 1 year ago

I'm also interested in this feature. My input:

I don't think the editing author is useful, since blog authors are explicitly defined.
I think the edit date should be displayed as "Updated \<date>" at the top rather than at the bottom of the post. (The original post date should be preserved, or there should be an option as to which date is displayed.)
We should allow for explicitly setting the edit date via frontmatter in addition to auto-detecting the date via the git history.
Whether this impacts the RSS feed order should be dependent on whether or not the original date is preserved/displayed.
If the RSS feed order is changed, will the date in the URL change as well? Again, I think this is dependent on whether or not the original date is preserved/displayed. But if the original date is hidden and the URL and feed is updated, then why not just republish the edited post with the new date and remove the original?

I'm no expert in SEO, but I agree we should take a careful and deliberate approach here instead of rushing into the implementation.

TheCatLady commented 1 year ago

As for why this feature may be useful: for my work, we're currently updating some of our previously published blog posts for SEO, and it's desirable to make it clear that the content has been updated since the original publish date.

slorber commented 1 year ago

As for why this feature may be useful: for my work, we're currently updating some of our previously published blog posts for SEO, and it's desirable to make it clear that the content has been updated since the original publish date.

Thanks for your feedback. As a blog post reader and newsletter curator, I also prefer when the creation date and update date are visible somewhere.

I think the edit date should be displayed as "Updated " at the top rather than at the bottom of the post

Agree, also looks better to me. I've seen a few blogs doing that already.

Whether this impacts the RSS feed order should be dependent on whether or not the original date is preserved/displayed.

Not a super fan of too magical behaviors like this. Will all users expect such behavior? At the same time we try to have sensible defaults so I don't know 🤷‍♂️

Maybe we should do nothing, and let users decide if they want to sort the feed themselves?

@johnnyreilly added a createFeedItems hook where you can re-order the feed based on the update date if you want to.

https://docusaurus.io/blog/releases/2.3#blog-createfeeditems

in addition to auto-detecting the date via the git history.

The tricky part is that if you want to edit a blog post typo or any other maintenance-related edit that is not significant, you maybe don't want that fix to have an effect on the last update date?

A scenario that we probably want to avoid: you edit a typo in a very old blog post, and now it's last edited in 2023, at the top of your RSS feed, and your feed readers get pinged to read it while content didn't really change...

This Git-based thing should probably not be a default? or maybe we shouldn't build it at all?

ZhymabekRoman commented 1 year ago

@slorber, Yes, I would like to use it on my blog. I needed this functionality when I updated the last article by adding and changing some applications from the list (see the last blog post). At least it would show that the article has been updated, as many blogs do. I apologise for being rude, it's been a bad day.

This Git-based thing should probably not be a default? or maybe we shouldn't build it at all?

I think making git-based blog page update by default is not required functional. Presonally I would like to manually enter the update date in the blog post properties.

slorber commented 1 year ago

Thanks for understand and the feedback.

So what I understand is that

we should only build the frontMatter last_update feature
we should not necessarily use the same design as docs
we can leave the RSS feed unchanged, createFeedItems is probable flexible enough to give control
we can wait for more feedback before implementing the git last-update to see if it's really useful

Any idea how the date should be integrated in the current design?

This looks a bit weird to me:

Any existing blog to share displaying an update date that we could use as an inspiration?

TheCatLady commented 1 year ago

in addition to auto-detecting the date via the git history.

The tricky part is that if you want to edit a blog post typo or any other maintenance-related edit that is not significant, you maybe don't want that fix to have an effect on the last update date?

I think correcting typos or broken links warrants updating the date IMO.

Otherwise, you could use the same argument for docs that maintenance-related edits shouldn't have an effect on the displayed date.

A scenario that we probably want to avoid: you edit a typo in a very old blog post, and now it's last edited in 2023, at the top of your RSS feed, and your feed readers get pinged to read it while content didn't really change...

Perhaps we shouldn't alter the feed order after all.

This Git-based thing should probably not be a default? or maybe we shouldn't build it at all?

Implementing the frontmatter option first sounds reasonable to me! The git-based option would just be a "nice-to-have" to avoid needing to manually manage the date value.

TheCatLady commented 1 year ago

Any idea how the date should be integrated in the current design?

If we want to keep things simple, maybe something like this:

Similar to how we mark the publish date with datePublished, we'd want to add the dateModified itemprop to the update date.

abcpeak commented 1 year ago

Similar to how we mark the publish date with datePublished, we'd want to add the dateModified itemprop to the update date.

How to edit blog data? datePublished was automatically generated according to the *.md file modify date, no need to write. Is that right?

Horsty80 commented 1 year ago

Hey :) i'm surprised this feature is available on docs, but not in blog What is the status about this feature ?

I've start migration my old blog to new one with docusaurus And i'rewrite all article and fix some mistake, but i want to keep the write date and add an update date :)

Can i help ?

Thanks

slorber commented 1 year ago

@Horsty80

i'm surprised this feature is available on docs, but not in blog

Those are different plugins, with different frontMatter, options and page layouts/designs

What is the status about this feature ? Can i help ?

I'm focusing on Docusaurus v3 (MDX 2 + React 18) and this feature is not a high priority on my todo list

Unless someone from the community steps in, and produces a final feature design + draft PR to review, this won't progress in the short term

ilg-ul commented 1 year ago

I'm also interested in such a feature.

My use case is a chronology site (a preview is available at https://cronica-it.github.io/preview/). The chronological events are blog posts with some additional metadata to define the event date and duration.

The posts are not write and forget, they are alive, and require updates from time to time, as more details are discovered related to the events.

It would be very useful to know who updated the post and when was it last updated. For this use case, with frequent updates, the date must be extracted automatically from the git date, since manually updating front matter properties is too tedious and error prone.

ilg-ul commented 9 months ago

I already implemented this feature in my fork, here is the commit:

https://github.com/cronica-it/docusaurus-chronology/commit/83e5293121aeb8c9b419be0fc0857cd56a5f72cc

ZhymabekRoman commented 9 months ago

@ilg-ul Great job! Thank you so much!

ilg-ul commented 9 months ago

Thank you @ZhymabekRoman, but wait for this to be upstreamed. There were many new features in my chronology fork and it'll take some time to integrate them.

ilg-ul commented 9 months ago

@slorber Sébastien, do you plan to cover this too with your colleague?

slorber commented 9 months ago

No, we still don't have a clear design for this feature afaik.

Note this feature is similar to https://github.com/facebook/docusaurus/issues/6218 in a way: we have an existing Markdown/MDX document and we want to display extra metadata about it somewhere in the theme.

This can now be implemented in userland starting Docusaurus v3.1 thanks to the parseFrontMatter hook: https://docusaurus.io/blog/releases/3.1#parsefrontmatter-hook See the comment I made here: https://github.com/facebook/docusaurus/issues/6218#issuecomment-1941157754

Since many of you want to implement this feature I'm going to post the recipe here too, adapted for this specific blog last update case.

The v3.1 parseFrontMatter hook allows you to automatically add a frontMatter.lastUpdated field to your blog posts (in case defining this manually is not an option)

async function getLastUpdated(filePath: string) {
  // Read the metadata you want from Git or any other system here...
  return {
    at: "3 O'clock", 
    by: "Seb", 
    picture: "https://github.com/slorber.png",
  }
} 

const config: Config = {
  markdown: {
    parseFrontMatter: async (params) => {
      const result = await params.defaultParseFrontMatter(params);
      const lastUpdated = await getLastUpdated(params.filePath);
      return {
        ...result,
        frontMatter: {
          ...result.frontMatter,
          lastUpdated,
        }
      }
    }
  },
}

export default config;

Then you can swizzle the blog component you want and render that front matter anywhere in the UI:

yarn docusaurus swizzle @docusaurus/theme-classic BlogPostItem/Footer --wrap --typescript

import React from 'react';
import Footer from '@theme-original/BlogPostItem/Footer';
import type FooterType from '@theme/BlogPostItem/Footer';
import type { WrapperProps } from '@docusaurus/types';
import { useBlogPost } from '@docusaurus/theme-common/internal';

type Props = WrapperProps<typeof FooterType>;

function LastUpdatedFooter() {
  const { frontMatter, isBlogPostPage } = useBlogPost();

  const lastUpdated = (frontMatter as any).lastUpdated as {
    at: string;
    by: string;
    picture: string;
  };

  // Do not show this data for paginated lists
  if (!lastUpdated || !isBlogPostPage) {
    return null;
  }

  return (
    <div
      style={{
        marginTop: 20,
        marginBottom: 20,
        display: 'flex',
        flexDirection: 'row',
        alignItems: 'center',
      }}
    >
      Last updated by{' '}
      <img
        src={lastUpdated.picture}
        style={{ margin: 5, width: 20, height: 20, borderRadius: 20 }}
      />{' '}
      {lastUpdated.by} at {lastUpdated.at}
    </div>
  );
}

export default function FooterWrapper(props: Props): JSX.Element {
  return (
    <>
      <Footer {...props} />
      <LastUpdatedFooter />
    </>
  );
}

Result:

Runnable sandbox: https://stackblitz.com/edit/github-kk5bsa?file=docusaurus.config.ts,src%2Ftheme%2FBlogPostItem%2FFooter%2Findex.tsx

Considering it is possible to implement in userland thanks to existing Docusaurus primitives, if we ever add this feature to Docusaurus core, this would only be an "opinionated shortcut" to the above solution.

By opinionated I mean: limited to reading history on Git (and not other VCS), and displaying the last update date in some predefined place such as the blog footer. This also means our opinions won't please everyone.

For this reason, there's no reason to rush implementing this feature officially. I'd rather see a few successful userland implementations first so that we understand the common denominator of the solutions, which would help us craft a good opinionated solution that pleases a maximum number of users.

ilg-ul commented 9 months ago

Given that this feature is already implemented for docs pages, why not provide the same implementation for blog posts, and, only for more complicated use cases, expect the users to swizzle and change the look?

I did exactly this in my fork, and I think that this solution might be acceptable for most of the regular users, who are not very keen to swizzle and write a lot of code for a relatively small feature.

Any other opinions on this solution? Is it acceptable as a common denominator?

slorber commented 9 months ago

@ilg-ul as you can see @TheCatLady has different opinions from yours.

https://github.com/facebook/docusaurus/issues/8657#issuecomment-1442377798

https://github.com/facebook/docusaurus/issues/8657#issuecomment-1440690880

If we implement what you like, other users might not like it.
If we implement what other users like, you might not like it.

The goal of designing a feature is to find a solution that most users will like. If we can all agree on what should be implemented, the implementation is likely easy.

The hard part is to figure out what should be implemented in the first place.

If I see 10 sites with userland implementations of this feature, 9 of them have opinion A and 1 of them has opinion B, we know that it's more likely users want us to implement opinion A, and can find a common denominator that would satisfy the subtleties of 9 implementations.

Also there's a big difference between someone having a theorical opinion in a GitHub comment, and someone really shipping his opinion to a production website.

In your case, you have a concrete demo of your opinion running live, so it adds weight to your comment: https://cronica-it.github.io/evenimente/2023/conferinta-dtc-30-ani-internet/

(but as you can see there's probably some design to fix 🤪 )

So, I'm not against implementing it, but I'd like to know first if people can agree on this design.

And if you disagree with the design proposed by @ilg-ul, what is your alternative solution?

Now that there is a provided solution to implement your alternative solution, are you willing to ship it to production to prove that you stand by your opinion?

Please vote on this comment:

👍
👎

And eventually: add a comment explaining your choice if you have something interesting to say.

ilg-ul commented 9 months ago

Ah, sorry, I don't want to appear smarter than I am, I'm not suggesting any design in particular, I'm only suggesting, for consistency reasons, to use the same design for docs and for blog posts, whatever it is.

So, if the design used for docs is not good, it must be improved, to the point where it can be used everywhere, in docs and in blog posts too.

As for the actual format used to display the text, for me it is not relevant, I'm fine with the one used for docs; if the majority of the users got used to it and find it acceptable, the minority can swizzle the components and customise them.

Anyway, before voting for a specific look, I think that we should decide between your current solution (not implementing anything and asking everyone wanting to use it to accept the pain of swizzling) and a solution based on a common denominator, consistent with the docs, where only a minority will have to swizzle.

My vote goes to consistency and avoiding swizzling.

slorber commented 9 months ago

Agree 👍

Unless someone is against this idea, we'll start working on a PR with my apprentice

@TheCatLady if you don't like the proposal above, now is the best time to push back 😉

ilg-ul commented 9 months ago

we'll start working on a PR with my apprentice

Feel free to reuse any parts of my commit (https://github.com/cronica-it/docusaurus-chronology/commit/83e5293121aeb8c9b419be0fc0857cd56a5f72cc). And be sure you fix that css that I messed ;-)

dkoprowski commented 9 months ago

Hello, I'm also interested in that feature. I swizzled src/theme/BlogPostItem/Header/Info/index.js specially for that case but I would be happy if it was included in main codebase.

When it comes to SEO it has to use the itemprop="dateModified" attribute as described on Google documentation e.g.

<time datetime="2020-05-27T00:00:00.000Z" itemprop="dateModified">May 27, 2020</time>

It also has to be in ISO 8601 format which I ignored at first and google pointed it out in their tooling 😛.

On my fork, I did this after a spacer and made dates italic:

slorber commented 9 months ago

Thanks, we'll have to remember to add the dateModified Structured Data as well (but I can count on @johnnyreilly to remind us on that 🤪 ).

Note: we recently migrated from Microdata to JSON+LD since Google prefers that: https://github.com/facebook/docusaurus/pull/9669 (will be in Docusaurus v3.3+, not 3.2)

slorber commented 8 months ago

Similarly to the docs plugin, Docusaurus v3.2 will have blog last update dates if you turn on the blog plugin options. You can override those with custom front matter.

PR: https://github.com/facebook/docusaurus/pull/9912

Preview: https://deploy-preview-9912--docusaurus-2.netlify.app/blog/releases/3.1/

We keep the same design as for docs last update UI. If you want another UX/UI you can swizzle the appropriate blog components, the last update metadata is available here.

facebook / docusaurus