Add configurable timestamping for posts

[KatieTheDev]

In #493, I discussed potential PR ideas for this feature but I decided to just do it. A demonstration of it working can be found at https://katiethe.dev or my site repo.

I have modified index.html, list.html, and single.html. These files all now have configurable timestamping, not just datestamping.

To enable the new feature, set showPostTime to true in hugo.toml. If you want seconds enabled, set postTimeSeconds to true. Both are false by default.

You can also individually set these params to true in front matter.

[KatieTheDev]

I suggest closing #493 if this PR is accepted. If any changes are requested I would be happy to do so.

[KatieTheDev]

@panr any thoughts?

[KatieTheDev]

Overview

Completely revamped the system. You can now set any timestamp format in both the site config as well as page frontmatter. If I missed anything, please let me know. Full development timeline can be seen in my website's repository. Took some time and some revisions but this should work fairly well and is fully compatible with any formatting allowed in Hugo according to their docs.

You may notice the following snippet before each with chain:

{{- $date := .Date | time -}}

This statement assigns the .Date value as type time to the variable $date. This is done because Hugo can't seem to access the .Date value inside the with chain otherwise.

Any formatting set in page front matter takes priority over any value set in the default page config. If a value is not set it defaults to the "2006-01-02" format, which is what you originally had everything set to. This is done to ensure this is not a breaking change for any websites. This also means there is a safe default if people choose not to mess with the new config option. Documentation is provided on the README.md example config. This example is what I used to create my website, so I assume that is a common option.

Full explainer of what's going on:

Post dates use the following setup:

{{- $date := .Date | time -}}
{{- with .Params.dateFormat -}}
  {{- $date.Format . -}}
{{- else -}}
  {{- with .Site.Params.dateFormat -}}
    {{- $date.Format . -}}
  {{- else -}}
    {{- $date.Format "2006-01-02" -}}
  {{- end -}}
{{- end -}}

The first line, as stated above, sets the $date variable to equal the existing .Date variable, set in front matter. This allows the timestamp to be passed down into the rest of the with statements.

The next line {{- with .Params.dateFormat -}} checks whether the dateFormat value is set in front matter. In the new archetype I added, this is commented out by default. This is done to ensure users do not accidentally override their settings in the site config.

Any time you see {{- $date.Format . -}} or similar, it is using the format specified in the with statement to set the date format, and it is then displayed as text on the page.

After the first else statement, we check whether dateFormat is set in site config with {{- with .Site.Params.dateFormat -}}. If it is, we use that format. Otherwise, Hugo will move to the final else statement, setting the date format as "2006-01-02".

Last updated timestamps use the following format:

{{- if $.Site.Params.showLastUpdated -}}
  {{- $lastmod := .Lastmod | time -}}
  {{- with .Params.dateFormat -}}
     [{{- $lastmod.Format . -}}]
  {{- else -}}
    {{- with .Site.Params.dateFormat -}}
       [{{- $lastmod.Format . -}}]
    {{- else -}}
       [{{- $lastmod.Format "2006-01-02" -}}]
    {{- end -}}
  {{- end -}}
{{- end -}}

The first if statement checks whether the slowLastUpdated parameter is set in the site config. This is similar to how it is checked in the original setup. Next, $lastmod is set the same way as $date was above.

We then run through the same logic chain as above, but substituting $date for $lastmod. The brackets and   present in the date formats shown are for appearance. This places the last-modified time in brackets, similar to your original code. The   makes it so that you have spacing between the post date and the modified date. I thought it was somewhat ugly and lacked some much-needed space without it. Feel free to remove that (or ask me to) if you would rather preserve the original look. This is the only cosmetic change I have made with this PR.

[panr]

@KatieTheDev I like the second approach much more. I also have to check one more thing in the theme regarding the changes, and I'll let you know after the weekend.

[KatieTheDev]

@KatieTheDev I like the second approach much more. I also have to check one more thing in the theme regarding the changes, and I'll let you know after the weekend.

@panr I'm glad to hear. Hope everything works out for you. I'm excited to get this put in!

[panr]

@panr I'm glad to hear. Hope everything works out for you.

Yesterday — while I was testing it — I produced almost exactly the same code as yours, so I guess we are on the same page here ;-)

[KatieTheDev]

@panr I'm glad to hear. Hope everything works out for you.

Yesterday — while I was testing it — I produced almost exactly the same code as yours, so I guess we are on the same page here ;-)

Glad to hear!

[KatieTheDev]

@panr Bug discovered! I will be pushing an update to my documentation provided in the example config file. The bug: If you set your server to UTC timezone and the date format has a timezone abbreviation, it may sometimes show the UTC offset rather than the timezone abbreviation. I'm not sure what causes this, but I was able to fix the bug on my server by changing my timezone to my actual timezone.

[panr]

@KatieTheDev long time no see, sorry about that. I revisited this PR and found a bug regarding using the localization tokens (eg: :data_long etc.). I couldn't make it work 🤔

Not sure about the fix, but this helped:

{{- $date := .Date -}}
{{- with .Params.dateFormat -}}
       {{- $date | time.Format . -}}
{{- else -}}
       {{- with .Site.Params.dateFormat -}}
            {{- $date | time.Format . -}}
       {{- else -}}
            {{- $date.Format "2006-01-02" -}}
       {{- end -}}
{{- end -}}

It seems that time.Format is not being called properly when we try to declare time as a part of $date. Or maybe it's a bug with my version of Hugo (hugo v0.133.0-c9777473d1369f812d727a6c07dc57ad7be7bf62+extended).

Can you recreate the bug on your setup as well?