Merge commit '374d184e6747678364fd61f5faf328ec9205eb6b'

56 files changed, 360 insertions, 266 deletions

diff --git a/docs/content/content-management/cross-references.md b/docs/content/content-management/cross-references.md
index 8c3155c00..a2c0de26e 100644
--- a/docs/content/content-management/cross-references.md
+++ b/docs/content/content-management/cross-references.md
@@ -61,13 +61,6 @@ To be sure to get the correct reference in this case, use the full path:
 {{</* relref "events/my-birthday.md" */>}} => /events/my-birthday/
 {{< /code >}}
 
-{{< todo >}}Remove this warning when https://github.com/gohugoio/hugo/issues/3703 is released.{{< /todo >}}
-
-A relative document name must *not* begin with a slash (`/`).
-```
-{{</* relref "/events/my-birthday.md" */>}} => ""
-```
-
 ### With Multiple Output Formats
 
 If the page exists in multiple [output formats][], `ref` or `relref` can be used with a output format name:
diff --git a/docs/content/content-management/urls.md b/docs/content/content-management/urls.md
index c2c08a4d4..54ce81ee0 100644
--- a/docs/content/content-management/urls.md
+++ b/docs/content/content-management/urls.md
@@ -118,7 +118,7 @@ aliases:
 ---
 {{< /code >}}
 
-Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-blog-post/`.
+Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-post/`.
 
 ### Example: Aliases in Multilingual
 
@@ -222,7 +222,7 @@ Here's the same organization run with `hugo --uglyURLs`:
 .
 └── content
     └── about
-    |   └── _index.md  // <- https://example.com/about/index.html
+    |   └── _index.md  // <- https://example.com/about.html
     ├── post
     |   ├── firstpost.md   // <- https://example.com/post/firstpost.html
     |   ├── happy
diff --git a/docs/content/documentation.md b/docs/content/documentation.md
index b9db486aa..9371dbdf0 100644
--- a/docs/content/documentation.md
+++ b/docs/content/documentation.md
@@ -4,7 +4,6 @@ linktitle: Hugo
 description: Hugo is the world's fastest static website engine. It's written in Go (aka Golang) and developed by bep, spf13 and friends.
 date: 2017-02-01
 publishdate: 2017-02-01
-lastmod: 2017-02-01
 menu:
   main:
     parent: "section name"
@@ -16,4 +15,6 @@ aliases: []
 toc: false
 layout: documentation-home
 ---
-Hugo is the **world's fastest static website engine.** It's written in Go (aka Golang) and developed by [bep](https://github.com/bep), [spf13](https://github.com/spf13) and [friends](https://github.com/gohugoio/hugo/graphs/contributors). Below you will find some of the most common and helpful pages from our documentation.
+Hugo is the **world's fastest static website engine.** It's written in Go (aka Golang) and developed by [bep](https://github.com/bep), [spf13](https://github.com/spf13) and [friends](https://github.com/gohugoio/hugo/graphs/contributors). 
+
+Below you will find some of the most common and helpful pages from our documentation.
diff --git a/docs/content/functions/apply.md b/docs/content/functions/apply.md
index 72066273e..9690837d6 100644
--- a/docs/content/functions/apply.md
+++ b/docs/content/functions/apply.md
@@ -10,7 +10,7 @@ menu:
   docs:
     parent: "functions"
 keywords: [advanced]
-signature: ["apply COLLETION FUNCTION [PARAM...]"]
+signature: ["apply COLLECTION FUNCTION [PARAM...]"]
 workson: []
 hugoversion:
 relatedfuncs: []
@@ -20,16 +20,16 @@ aliases: []
 ---
 
 {{< todo >}}
-<!-- POTENTIAL NEW CONTENT: see apply/sequence discussion: https://discourse.gohugo.io/t/apply-printf-on-a-sequence/5722; -->
+POTENTIAL NEW CONTENT: see apply/sequence discussion: https://discourse.gohugo.io/t/apply-printf-on-a-sequence/5722;
 {{< /todo >}}
 
 `apply` expects at least three parameters, depending on the function being applied.
 
-1. The first parameter is the sequence to operate on
+1. The first parameter is the sequence to operate on.
 2. The second parameter is the name of the function as a string, which must be the name of a valid [Hugo function][functions].
 3. After that, the parameters to the applied function are provided, with the string `"."` standing in for each element of the sequence the function is to be applied against.
 
-Here is an example of a content file with `name:` as a front matter field:
+Here is an example of a content file with `names:` as a front matter field:
 
 ```
 +++
@@ -43,19 +43,19 @@ You can then use `apply` as follows:
 {{ apply .Params.names "urlize" "." }}
 ```
 
-Which will result as follows:
+Which will result in the following:
 
 ```
 "derek-perkins", "joe-bergevin", "tanner-linsley"
 ```
 
-This is *roughly* equivalent to using the following with [range][]
+This is *roughly* equivalent to using the following with [range][]:
 
 ```
 {{ range .Params.names }}{{ . | urlize }}{{ end }}
 ```
 
-However, it isn’t possible to provide the output of a range to the [`delimit` function][delimit], so you need to `apply` it.
+However, it is not possible to provide the output of a range to the [`delimit` function][delimit], so you need to `apply` it.
 
 If you have `post-tag-list.html` and `post-tag-link.html` as [partials][], you *could* use the following snippets, respectively:
 
diff --git a/docs/content/getting-started/configuration.md b/docs/content/getting-started/configuration.md
index 7b31931e5..5249e4fab 100644
--- a/docs/content/getting-started/configuration.md
+++ b/docs/content/getting-started/configuration.md
@@ -79,16 +79,10 @@ defaultContentLanguage:     "en"
 # Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
 defaultContentLanguageInSubdir: false
 disableLiveReload:          false
-# Do not build RSS files
-disableRSS:                 false
-# Do not build Sitemap file
-disableSitemap:             false
 # Enable GitInfo feature
 enableGitInfo:              false
 # Build robots.txt file
 enableRobotsTXT:            false
-# Do not render 404 page
-disable404:                 false
 # Do not inject generator meta tag on homepage
 disableHugoGeneratorInject: false
 # Allows you to disable all page types and will render nothing related to 'kind';
@@ -221,16 +215,10 @@ defaultContentLanguage =      "en"
 # Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
 defaultContentLanguageInSubdir =  false
 disableLiveReload =           false
-# Do not build RSS files
-disableRSS =                  false
-# Do not build Sitemap file
-disableSitemap =              false
 # Enable GitInfo feature
 enableGitInfo =               false
 # Build robots.txt file
 enableRobotsTXT =             false
-# Do not render 404 page
-disable404 =                  false
 # Do not inject generator meta tag on homepage
 disableHugoGeneratorInject =  false
 # Allows you to disable all page types and will render nothing related to 'kind';
diff --git a/docs/content/getting-started/installing.md b/docs/content/getting-started/installing.md
index eb605c2a6..bf0bde50d 100644
--- a/docs/content/getting-started/installing.md
+++ b/docs/content/getting-started/installing.md
@@ -70,7 +70,7 @@ choco install hugo -confirm
 
 #### Vendored Dependencies
 
-Hugo uses [dep][] to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository. Therefore, a simple `go get` is *not* supported because the command is not vendor aware. 
+Hugo uses [dep][] to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository. Therefore, a simple `go get` is *not* supported because the command is not vendor aware.
 
 The simplest way is to use [mage][] (a Make alternative for Go projects.)
 
@@ -79,7 +79,7 @@ The simplest way is to use [mage][] (a Make alternative for Go projects.)
 {{< code file="from-gh.sh" >}}
 go get github.com/magefile/mage
 go get -d github.com/gohugoio/hugo
-cd $HOME/go/src/github.com/gohugoio/hugo
+cd ${GOPATH:-$HOME/go}/src/github.com/gohugoio/hugo
 mage vendor
 mage install
 {{< /code >}}
diff --git a/docs/content/getting-started/usage.md b/docs/content/getting-started/usage.md
index bc988d27c..2ad2910f8 100644
--- a/docs/content/getting-started/usage.md
+++ b/docs/content/getting-started/usage.md
@@ -44,6 +44,7 @@ Usage:
 
 Available Commands:
   benchmark   Benchmark Hugo by building a site a number of times.
+  check       Contains some verification checks
   config      Print the site configuration
   convert     Convert your content to different formats
   env         Print Hugo version and environment info
@@ -61,18 +62,16 @@ Flags:
   -E, --buildExpired               include expired content
   -F, --buildFuture                include content with publishdate in the future
       --cacheDir string            filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
-      --canonifyURLs               if true, all relative URLs will be canonicalized using baseURL
+      --canonifyURLs               (deprecated) if true, all relative URLs will be canonicalized using baseURL
       --cleanDestinationDir        remove files from destination not found in static directories
       --config string              config file (default is path/config.yaml|json|toml)
   -c, --contentDir string          filesystem path to content directory
       --debug                      debug output
   -d, --destination string         filesystem path to write files to
-      --disable404                 do not render 404 page
       --disableKinds stringSlice   disable different kind of pages (home, RSS etc.)
-      --disableRSS                 do not build RSS files
-      --disableSitemap             do not build Sitemap file
       --enableGitInfo              add Git revision, date and author info to the pages
       --forceSyncStatic            copy all files when static is changed.
+      --gc                         enable to run some cleanup tasks (remove unused cache files) after the build
   -h, --help                       help for hugo
       --i18n-warnings              print missing translations
       --ignoreCache                ignores the cache directory
@@ -81,23 +80,21 @@ Flags:
       --logFile string             log File path (if set, logging enabled automatically)
       --noChmod                    don't sync permission mode of files
       --noTimes                    don't sync modification time of files
-      --pluralizeListTitles        pluralize titles in lists using inflect (default true)
-      --preserveTaxonomyNames      preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
+      --pluralizeListTitles        (deprecated) pluralize titles in lists using inflect (default true)
+      --preserveTaxonomyNames      (deprecated) preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
       --quiet                      build in quiet mode
       --renderToMemory             render to memory (only useful for benchmark testing)
   -s, --source string              filesystem path to read files relative from
       --stepAnalysis               display memory and timing of different steps of the program
       --templateMetrics            display metrics about template executions
+      --templateMetricsHints       calculate some improvement hints when combined with --templateMetrics
   -t, --theme string               theme to use (located in /themes/THEMENAME/)
       --themesDir string           filesystem path to themes directory
-      --uglyURLs                   if true, use /filename.html instead of /filename/
+      --uglyURLs                   (deprecated) if true, use /filename.html instead of /filename/
   -v, --verbose                    verbose output
       --verboseLog                 verbose logging
   -w, --watch                      watch filesystem for changes and recreate as needed
 
-Additional help topics:
-  hugo check     Contains some verification checks
-
 Use "hugo [command] --help" for more information about a command.
 ```
 
diff --git a/docs/content/hosting-and-deployment/hosting-on-gitlab.md b/docs/content/hosting-and-deployment/hosting-on-gitlab.md
index c38908cae..9c4a8978a 100644
--- a/docs/content/hosting-and-deployment/hosting-on-gitlab.md
+++ b/docs/content/hosting-and-deployment/hosting-on-gitlab.md
@@ -20,6 +20,14 @@ wip: false
 aliases: [/tutorials/hosting-on-gitlab/]
 ---
 
+{{% warning %}}
+GitLab has temporarily turned off custom domains support because of a security issue. The plan is to re-enable it after the 20th of February.
+For more information:
+https://about.gitlab.com/2018/02/05/gitlab-pages-custom-domain-validation/
+{{% /warning %}}
+
+{{< todo >}}Remove the above when fixed.{{< /todo >}}
+
 [GitLab](https://gitlab.com/) makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides [native support for Hugo, as well as numerous other static site generators](https://gitlab.com/pages/hugo).
 
 ## Assumptions
diff --git a/docs/content/hosting-and-deployment/hosting-on-netlify.md b/docs/content/hosting-and-deployment/hosting-on-netlify.md
index def152b36..fca639fac 100644
--- a/docs/content/hosting-and-deployment/hosting-on-netlify.md
+++ b/docs/content/hosting-and-deployment/hosting-on-netlify.md
@@ -59,37 +59,33 @@ Select the repo you want to use for continuous deployment. If you have a large n
 
 Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you wanted published, your [build command][], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration][config], the default of which is `public`. The following steps assume you are publishing from the `master` branch.
 
-### Build with a Specific Hugo Version
+## Configure Hugo Version in Netlify 
 
-Setting the build command to `hugo` will build your site according to the current default Hugo version used by Netlify. You can see the full list of [available Hugo versions in Netlify's Docker file][hugoversions].
-
-If you want to tell Netlify to build with a specific version (hugo <= 0.20), you can append an underscore followed by the version number to the build command:
-
-```
-hugo_0.19
-```
-
-Your simple configuration should now look similar to the following:
-
-![Screenshot of 3-step, basic continuous deployment setup with a new Hugo site on Netlify](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-3.jpg)
-
-For version hugo > 0.20 you have to [specify version hugo for testing and production](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console.
+You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for your environments in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console.
 
 For production:
 
 ```
 [context.production.environment]
-  HUGO_VERSION = "0.26"
+  HUGO_VERSION = "0.36"
 ```
 
 For testing:
 
 ```
 [context.deploy-preview.environment]
-  HUGO_VERSION = "0.26"
-```  
+  HUGO_VERSION = "0.36"
+```
+
+The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`:
 
-Selecting "Deploy site" will immediately take you to a terminal for your build:.
+{{< code file="netlify.toml" nocode="true" >}}
+{{< readfile file="netlify.toml" highlight="toml" >}}   
+{{< /code >}}
+
+## Build and Deploy Site
+
+In the Netlify console, selecting "Deploy site" will immediately take you to a terminal for your build:.
 
 ![Animated gif of deploying a site to Netlify, including the terminal read out for the build.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploying-site.gif)
 
@@ -103,6 +99,8 @@ Once the build is finished---this should only take a few seconds--you should now
 
 Now every time you push changes to your hosted git repository, Netlify will rebuild and redeploy your site.
 
+See [this blog post](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for more details about how Netlify handles Hugo versions.
+
 ## Use Hugo Themes with Netlify
 
 The [`git clone` method for installing themes][installthemes] is not supported by Netlify. If you were to use `git clone`, it would