docs: Add docs on the new front matter configuration - hugo - [fork] hugo port for 9front
HTML git clone git@git.drkhsh.at/hugo.git
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
DIR commit 0dbf79c2f8cd5b1a5c91c04a8d677f956b0b8fe8
DIR parent f12ad7d56afbf7655f891139dd2f724347fcff60
HTML Author: Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>
Date: Sun, 11 Mar 2018 22:51:11 +0100
docs: Add docs on the new front matter configuration
See #4495
Diffstat:
M docs/content/getting-started/confi… | 66 ++++++++++++++++++++++++++++++-
1 file changed, 65 insertions(+), 1 deletion(-)
---
DIR diff --git 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.