ref: 0dbf79c2f8cd5b1a5c91c04a8d677f956b0b8fe8
parent: f12ad7d56afbf7655f891139dd2f724347fcff60
author: Bjørn Erik Pedersen <[email protected]>
date: Sun Mar 11 18:51:11 EDT 2018
docs: Add docs on the new front matter configuration See #4495
--- a/docs/content/getting-started/configuration.md
+++ b/docs/content/getting-started/configuration.md
@@ -80,6 +80,10 @@
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 @@
-
## Configure with Environment Variables
In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables.
@@ -298,6 +301,67 @@
```
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