Configure front matter

Dates

There are four methods on a Page object that return a date.

Hugo determines the values to return based on this configuration:

frontmatter:
  date:
  - date
  - publishdate
  - pubdate
  - published
  - lastmod
  - modified
  expiryDate:
  - expirydate
  - unpublishdate
  lastmod:
  - :git
  - lastmod
  - modified
  - date
  - publishdate
  - pubdate
  - published
  publishDate:
  - publishdate
  - pubdate
  - published
  - date

[frontmatter]
  date = ['date', 'publishdate', 'pubdate', 'published', 'lastmod', 'modified']
  expiryDate = ['expirydate', 'unpublishdate']
  lastmod = [':git', 'lastmod', 'modified', 'date', 'publishdate', 'pubdate', 'published']
  publishDate = ['publishdate', 'pubdate', 'published', 'date']

{
   "frontmatter": {
      "date": [
         "date",
         "publishdate",
         "pubdate",
         "published",
         "lastmod",
         "modified"
      ],
      "expiryDate": [
         "expirydate",
         "unpublishdate"
      ],
      "lastmod": [
         ":git",
         "lastmod",
         "modified",
         "date",
         "publishdate",
         "pubdate",
         "published"
      ],
      "publishDate": [
         "publishdate",
         "pubdate",
         "published",
         "date"
      ]
   }
}

The ExpiryDate method, for example, returns the expirydate value if it exists, otherwise it returns unpublishdate.

You can also use custom date parameters:

frontmatter:
  date:
  - myDate
  - date

[frontmatter]
  date = ['myDate', 'date']

{
   "frontmatter": {
      "date": [
         "myDate",
         "date"
      ]
   }
}

In the example above, the Date method returns the myDate value if it exists, otherwise it returns date.

To fall back to the default sequence of dates, use the :default token:

frontmatter:
  date:
  - myDate
  - :default

[frontmatter]
  date = ['myDate', ':default']

{
   "frontmatter": {
      "date": [
         "myDate",
         ":default"
      ]
   }
}

In the example above, the Date method returns the myDate value if it exists, otherwise it returns the first valid date from date, publishdate, pubdate, published, lastmod, and modified.

Aliases

Some of the front matter fields have aliases.

The default front matter configuration includes these aliases.

Tokens

Hugo provides the following tokens to help you configure your front matter:

:default

The default ordered sequence of date fields.

:fileModTime

The file’s last modification timestamp.

:filename

Extracts the date from the file name, provided the file name begins with a date in one of the following formats:

• YYYY-MM-DD
• YYYY-MM-DD-HH-MM-SS New in v0.148.0

Within the YYYY-MM-DD-HH-MM-SS format, the date and time values may be separated by any character including a space (e.g., 2025-02-01T14-30-00).

Hugo resolves the extracted date to the timeZone defined in your site configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page’s slug, but only if you haven’t already specified a slug in the page’s front matter.

For example, if you name your file 2025-02-01-article.md, Hugo will set the date to 2025-02-01 and the slug to article.

:git

The Git author date for the file’s last revision. To enable access to the Git author date, set enableGitInfo to true, or use the --enableGitInfo flag when building your site.

Example

Consider this site configuration:

frontmatter:
  date:
  - :filename
  - :default
  lastmod:
  - lastmod
  - :fileModTime

[frontmatter]
  date = [':filename', ':default']
  lastmod = ['lastmod', ':fileModTime']

{
   "frontmatter": {
      "date": [
         ":filename",
         ":default"
      ],
      "lastmod": [
         "lastmod",
         ":fileModTime"
      ]
   }
}

To determine date, Hugo tries to extract the date from the file name, falling back to the default ordered sequence of date fields.

To determine lastmod, Hugo looks for a lastmod field in front matter, falling back to the file’s last modification timestamp.