docs: Add docs on the new front matter configuration

See #4495

1 files changed, 65 insertions, 1 deletions

diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md
index b051347d8..8fd72290f 100644
--- a/docs/content/getting-started/configuration.md
+++ b/docs/content/getting-started/configuration.md
@@ -80,6 +80,10 @@ enableMissingTranslationPlaceholders (false)
 enableRobotsTXT (false)
 : When enabled, Hugo will generate a `robots.txt` file.
 
+frontmatter
+
+: See [Front matter Configuration](#configure-front-matter).
+
 footnoteAnchorPrefix ("")
 : A prefix for your footnote anchors.
 
@@ -268,7 +272,6 @@ title = "My Hugo Site"
 
 
 
-
 ## Configure with Environment Variables
 
 In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables.
@@ -299,6 +302,67 @@ ignoreFiles = [ "\\.foo$", "\\.boo$" ]
 
 The above is a list of regular expressions. Note that the backslash (`\`) character is escaped in this example to keep TOML happy.
 
+## Configure Front Matter
+
+### Configure Dates
+
+Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `config.toml`.
+
+
+The default configuration is:
+
+```toml
+[frontmatter]
+date = ["date","publishDate", "lastmod"]
+lastmod = [":git" "lastmod", "date","publishDate"]
+publishDate = ["publishDate", "date"]
+expiryDate = ["expiryDate"]
+```
+
+If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`:
+
+ ```toml
+[frontmatter]
+date = [ "myDate", ":default"]
+```
+
+The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date.
+
+In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration.  Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`.
+
+The special date handlers are:
+
+
+`:fileModTime`
+: Fetches the date from the content file's last modification timestamp.
+
+An example:
+
+ ```toml
+[frontmatter]
+lastmod = ["lastmod" ,":fileModTime", ":default"]
+```
+
+
+The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`.
+
+
+`:filename`
+: Fetches the date from the content file's filename. For example, `218-02-22-mypage.md` will extract the date `218-02-22`. Also, if `slug is not set, `mypage` will be used as the value for `.Slug`.
+
+An example:
+
+```toml
+[frontmatter]
+date  = [":filename", ":default"]
+```
+
+The above will try first to extract the value for `.Date` from the filename, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`.
+
+
+`:git`
+: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site config.
+
 ## Configure Blackfriday
 
 [Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine.