Feature Request: Optional "last updated" date in default theme

[frankdugan3]

It may be useful to have an optional "last updated" timestamp displayed on a page, especially for docs that may not be tied to specific release versions.

I was thinking this could be automated nicely with git during build on a page-by-page basis with something like:

git log -1 --format="%ct" [file]
# returns timestamp in seconds of last commit of file
# easily used to create JS Date

Could also do the whole docs directory in one batch with something like:

git ls-tree -r --name-only HEAD docs | while read filename; do echo "$(git log -1 --format="%ct" -- $filename) $filename"; done
# returns lines of "timestamp filepath"
# could be modified to return a JSON array

If anyone likes this idea, do you have preferences on where the timestamp would be displayed? Next to the edit link or under page header?

I would be happy to attempt an implementation if this is of interest.

[meteorlxy]

I was also thinking about this idea yesterday.

That would be useful when using vuepress to write blog, too.

[ulivz]

The default theme is going to be focused on documentation sites, this feature should be done at the separate blog theme, let's move to Blog Support roadmap to continue discussion.

[meteorlxy]

@ulivz

His idea is:

especially for docs that may not be tied to specific release versions.

which is not specific for blog.

[meteorlxy]

@yyx990803

Hi Evan. Will this feature be useful for documentation sites?

[frankdugan3]

To clarify, I'm thinking of specific cases like examples, tutorials, style guides, etc. Things that might cover multiple versions of a library/software etc.

[yyx990803]

This probably doesn't have to be in the default theme but something in core to add a last updated field on page objects could be useful.

[eyleron]

FWIW, I see Google Maps, for instance, uses a Last Updated in their documentation.

[andyczerwonka]

I think it’s very useful in the default theme. Optional of course.

[ulivz]

Found a problem, there is a quick implementation (#282) by using fs.stat. but having a small issue, if you change file content, then you cancel the change, but in that time you only submit one commit, the git last modified time of this file will not be changed, but last modified time of fs.stat will be changed.

Which way do you think we should use to get the last modified time?

[ycmjason]

@ulivz can we have both? :D

[ulivz]

@ycmjason Sure, we can have both.

[meteorlxy]

In my opinion, we should not use fs.stat.

fs.stat tracks the file itself on your filesystem. That means, even git clone the repository to another directory would make the result of fs.stat different.

If we use fs.stat, a certain snapshot could have different Last Modified, which makes no sense, right?

[ulivz]

Can anyone help to confirm which Hexo leverage ?

[meteorlxy]

In Hexo, we can set a updated field in frontmatter, which will be used to generate a moment.js object.

[ulivz]

So it's just configured manually?

[ycmjason]

Definitely prefer automatically generated dates.

[yyx990803]

I think we should use git for the reason mentioned by @meteorlxy here.

Fs creation/modify time is not that useful especially if the site is built on a CI server every time. You will get the same timestamp for every file...

[ulivz]

Will release it at 0.9.0: #419. 🚀