Hugo Date vs PublishDate

Question

Hugo offers a few date page variables:

• Date - the date associated with the page
• PublishDate - the date on which the content was or will be published
• LastMod - the date the content was last modified
• ExpiryDate - the date on which the content is scheduled to expire

LastMod and ExpiryDate make sense to me, but I am puzzled as to the difference between Date and PublishDate.

What are some examples of when Date and PublishDate are different?

Answer 1

If...

1. you are using the default meaning of date and publishDate (see below),
2. both are defined for a page,
3. and date is different from publishDate

Then...

• publishDate is used to determine if a page is in the future (i.e. if hugo's -F or --buildFuture flag is required for the page to be built)
• date is used to order pages in the default ordering (Weight > Date > LinkTitle > Title > FilePath).[*] The default order is used in next/previous navigation and can be used in a range.

Configuring dates is discussed in https://gohugo.io/getting-started/configuration/#configure-front-matter. Here is the default for date and publishDate:

frontmatter:
  date:
    - date
    - publishDate
    - lastmod
  publishDate:
    - publishDate
    - date

Because I want date and publishDate to mean the same thing, I have the following in my config.yaml:

frontmatter:
  date: 
    - publishDate
    - :filename
    - date
    - :fileModTime
  publishDate: 
    - publishDate
    - :filename
    - date
    - :fileModTime

I've made them the same because I, too, was puzzled by their difference!

[*] Info about ordering content in Hugo is at https://gohugo.io/templates/lists/#order-content