docs: Add docs on the new front matter configuration

See #4495
This commit is contained in:
Bjørn Erik Pedersen 2018-03-11 22:51:11 +01:00
parent f12ad7d56a
commit 0dbf79c2f8
No known key found for this signature in database
GPG key ID: 330E6E2BD4859D8F

View file

@ -80,6 +80,10 @@ enableMissingTranslationPlaceholders (false)
enableRobotsTXT (false) enableRobotsTXT (false)
: When enabled, Hugo will generate a `robots.txt` file. : When enabled, Hugo will generate a `robots.txt` file.
frontmatter
: See [Front matter Configuration](#configure-front-matter).
footnoteAnchorPrefix ("") footnoteAnchorPrefix ("")
: A prefix for your footnote anchors. : A prefix for your footnote anchors.
@ -268,7 +272,6 @@ title = "My Hugo Site"
## Configure with Environment Variables ## Configure with Environment Variables
In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system 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. 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 ## Configure Blackfriday
[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine. [Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine.