Squashed 'docs/' changes from 93f7baf80..3f95a2ace

3f95a2ace Update merge function examples (#1662)
e8d518011 requires -> require typo fix (#1666)
e714066cb Update GitLab deployment instructions (#1661)
11946a218 update GitLab CI/CD yaml syntax (#1649)
3568ddc03 Add explicit `contentDir` to module-config-mounts (#1658)
798ac8f68 Add default value to isHTML
d376565ce Create extensions.json

git-subtree-dir: docs
git-subtree-split: 3f95a2ace37b04851905d72e4444020e30996787

.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "EditorConfig.EditorConfig",
+    "esbenp.prettier-vscode",
+  ]
+}

content/en/functions/merge.md

@@ -1,6 +1,6 @@
 ---
 title: merge
-description: "`merge` deep merges two maps and returns the resulting map."
+description: "Returns the result of merging two or more maps."
 date: 2019-08-08
 categories: [functions]
 menu:
@@ -14,28 +14,58 @@ relatedfuncs: [dict, append, reflect.IsMap, reflect.IsSlice]
 aliases: []
 ---
 
-Merge creates a copy of the final `MAP` and merges any preceding `MAP` into it in reverse order.
+Returns the result of merging two or more maps from left to right. If a key already exists, `merge` updates its value. If a key is absent, `merge` inserts the value under the new key.
+
 Key handling is case-insensitive.
 
-An example merging two maps.
+The following examples use these map definitions:
 
 ```go-html-template
-{{ $default_params := dict "color" "blue" "width" "50%" "height" "25%" "icon" "star" }}
+{{ $m1 := dict "x" "foo" }}
-{{ $user_params := dict "color" "red" "icon" "mail" "extra" (dict "duration" 2) }}
+{{ $m2 := dict "x" "bar" "y" "wibble" }}
-{{ $params := merge $default_params $user_params }}
+{{ $m3 := dict "x" "baz" "y" "wobble" "z" (dict "a" "huey") }}
 ```
 
-Resulting __$params__:
+Example 1
 
+```go-html-template
+{{ $merged := merge $m1 $m2 $m3 }}
+
+{{ $merged.x }}   --> baz
+{{ $merged.y }}   --> wobble
+{{ $merged.z.a }} --> huey
 ```
-"color": "red"
+
-"extra":
+Example 2
-  "duration": 2
+
-"height": "25%"
+```go-html-template
-"icon": "mail"
+{{ $merged := merge $m3 $m2 $m1 }}
-"width": "50%"
+
+{{ $merged.x }}   --> foo
+{{ $merged.y }}   --> wibble
+{{ $merged.z.a }} --> huey
+```
+
+Example 3
+
+```go-html-template
+{{ $merged := merge $m2 $m3 $m1 }}
+
+{{ $merged.x }}   --> foo
+{{ $merged.y }}   --> wobble
+{{ $merged.z.a }} --> huey
+```
+
+Example 4
+
+```go-html-template
+{{ $merged := merge $m1 $m3 $m2 }}
+
+{{ $merged.x }}   --> bar
+{{ $merged.y }}   --> wibble
+{{ $merged.z.a }} --> huey
 ```
 
 {{% note %}}
-  Regardless of depth, merging only applies to maps. For slices, use [append]({{< ref "functions/append" >}})
+Regardless of depth, merging only applies to maps. For slices, use [append]({{< ref "functions/append" >}}).
 {{% /note %}}

content/en/hosting-and-deployment/hosting-on-gitlab.md

@@ -1,7 +1,7 @@
 ---
 title: Host on GitLab
 linktitle: Host on GitLab
-description: GitLab makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo.
+description: GitLab makes it easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo.
 date: 2016-06-23
 publishdate: 2016-06-23
 lastmod: 2017-11-16
@@ -20,25 +20,23 @@ wip: false
 aliases: [/tutorials/hosting-on-gitlab/]
 ---
 
-[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
 
 * Working familiarity with Git for version control
-* Completion of the Hugo [Quick Start][]
+* Completion of the Hugo [Quick Start]
 * A [GitLab account](https://gitlab.com/users/sign_in)
 * A Hugo website on your local machine that you are ready to publish
 
-## Create .gitlab-ci.yml
+## BaseURL
 
-```
+The `baseURL` in your [site configuration](/getting-started/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://<YourUsername>.gitlab.io/<your-hugo-site>/`) and not a custom domain.
-cd your-hugo-site
-```
 
-In the root directory of your Hugo site, create a `.gitlab-ci.yml` file. The `.gitlab-ci.yml` configures the GitLab CI on how to build your page. Simply add the content below.
+## Configure GitLab CI/CD
+
+Define your [CI/CD](https://docs.gitlab.com/ee/ci/quick_start/) jobs by creating a `.gitlab-ci.yml` file in the root of your project.
 
 {{< code file=".gitlab-ci.yml" >}}
-image: registry.gitlab.com/pages/hugo:latest
+image: registry.gitlab.com/pages/hugo/hugo_extended:latest
 
 variables:
   GIT_SUBMODULE_STRATEGY: recursive
@@ -49,19 +47,19 @@ pages:
   artifacts:
     paths:
     - public
-  only:
+  rules:
-  - master
+  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 {{< /code >}}
 
 {{% note %}}
-All available Hugo versions are listed [here](https://gitlab.com/pages/hugo/container_registry)
+See [this list](https://gitlab.com/pages/hugo/container_registry) if you wish to use a particular Hugo version to build your site.
 {{% /note %}}
 
 ## Push Your Hugo Website to GitLab
 
 Next, create a new repository on GitLab. It is *not* necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
 
-```
+```bash
 # initialize new git repository
 git init
 
@@ -81,10 +79,6 @@ That's it! You can now follow the CI agent building your page at `https://gitlab
 
 After the build has passed, your new website is available at `https://<YourUsername>.gitlab.io/<your-hugo-site>/`.
 
-{{% note %}}
-Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitLab pages repository if you're using the default GitLab Pages URL (e.g., `https://<YourUsername>.gitlab.io/<your-hugo-site>/`) and not a custom domain.
-{{% /note %}}
-
 ## Next Steps
 
 GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/).

content/en/hugo-modules/configuration.md

@@ -113,7 +113,7 @@ noVendor
 ## Module Config: mounts
 
 {{% note %}}
-When the `mounts` config was introduced in Hugo 0.56.0, we were careful to preserve the existing `staticDir` and similar configuration to make sure all existing sites just continued to work. But you should not have both: if you add a `mounts` section you should remove the old `staticDir` etc. settings.
+When the `mounts` config was introduced in Hugo 0.56.0, we were careful to preserve the existing `contentDir`, `staticDir`, and similar configuration to make sure all existing sites just continued to work. But you should not have both: if you add a `mounts` section you should remove the old `contentDir`, `staticDir`, etc. settings.
 {{% /note %}}
 
 {{% warning %}}

content/en/templates/output-formats.md

@@ -112,7 +112,7 @@ The following is the full list of configuration options for output formats and t
 : use Go's plain text templates parser for the templates. **Default:** `false`.
 
 `isHTML`
-: used in situations only relevant for `HTML`-type formats; e.g., page aliases.
+: used in situations only relevant for `HTML`-type formats; e.g., page aliases. **Default:** `false`.
 
 `noUgly`
 : used to turn off ugly URLs If `uglyURLs` is set to `true` in your site. **Default:** `false`.

layouts/shortcodes/gomodules-info.html

@@ -1,5 +1,5 @@
 {{ $text := `
-Most of the commands for **Hugo Modules** requires a newer version of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ). If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.12 in your Environment settings.
+Most of the commands for **Hugo Modules** require a newer version of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ). If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.12 in your Environment settings.
 
 For more information about Go Modules, see: