Merge commit '047c4188dfc854f658d16f1e4a9501f9c97a31c7'

41 files changed, 12138 insertions, 368 deletions

diff --git a/docs/content/about/new-in-032/index.md b/docs/content/about/new-in-032/index.md
index 41bd58937..b8ca6430e 100644
--- a/docs/content/about/new-in-032/index.md
+++ b/docs/content/about/new-in-032/index.md
@@ -61,7 +61,7 @@ Note that changes to any resource inside the `content` folder will trigger a rel
 
 #### List all Resources
 
-```html
+```go-html-template
 {{ range .Resources }}
 <li><a href="{{ .RelPermalink }}">{{ .ResourceType | title }}</a></li>
 {{ end }}
@@ -73,7 +73,7 @@ For an absolute URL, use `.Permalink`.
 
 #### List All Resources by Type
 
-```html
+```go-html-template
 {{ with .Resources.ByType "image" }}
 {{ end }}
 
@@ -83,7 +83,7 @@ Type here is `page` for pages, else the main type in the MIME type, so `image`,
 
 #### Get a Specific Resource
 
-```html
+```go-html-template
 {{ $logo := .Resources.GetByPrefix "logo" }}
 {{ with $logo }}
 {{ end }}
@@ -91,7 +91,7 @@ Type here is `page` for pages, else the main type in the MIME type, so `image`,
 
 #### Include Page Resource Content
 
-```html
+```go-html-template
 {{ with .Resources.ByType "page" }}
 {{ range . }}
 <h3>{{ .Title }}</h3>
@@ -146,7 +146,7 @@ This is the shortcode used in the examples above:
 
 And it is used like this:
 
-```html
+```go-html-template
 {{</* imgproc sunset Resize "300x" */>}}
 ```
 
diff --git a/docs/content/content-management/comments.md b/docs/content/content-management/comments.md
index 355bf0042..20932a825 100644
--- a/docs/content/content-management/comments.md
+++ b/docs/content/content-management/comments.md
@@ -27,15 +27,11 @@ Hugo comes with all the code you need to load Disqus into your templates. Before
 
 ### Configure Disqus
 
-Disqus comments require you set a single value in your [site's configuration file][configuration]. The following show the configuration variable in a `config.toml` and `config.yml`, respectively:
+Disqus comments require you set a single value in your [site's configuration file][configuration] like so:
 
-```
+{{< code-toggle copy="false" >}}
 disqusShortname = "yourdiscussshortname"
-```
-
-```
-disqusShortname: "yourdiscussshortname"
-```
+{{</ code-toggle >}}
 
 For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file:
 
diff --git a/docs/content/content-management/front-matter.md b/docs/content/content-management/front-matter.md
index a6a3f2403..2fc18ee31 100644
--- a/docs/content/content-management/front-matter.md
+++ b/docs/content/content-management/front-matter.md
@@ -34,9 +34,9 @@ YAML
 JSON
 : a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
 
-### TOML Example
+### Example
 
-```
+{{< code-toggle >}}
 +++
 title = "spf13-vim 3.0 release and new website"
 description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
@@ -48,39 +48,7 @@ categories = [
 ]
 slug = "spf13-vim-3-0-release-and-new-website"
 +++
-```
-
-### YAML Example
-
-```
----
-title: "spf13-vim 3.0 release and new website"
-description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
-tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ]
-lastmod: 2015-12-23
-date: "2012-04-06"
-categories:
-  - "Development"
-  - "VIM"
-slug: "spf13-vim-3-0-release-and-new-website"
----
-```
-
-### JSON Example
-
-```
-{
-    "title": "spf13-vim 3.0 release and new website",
-    "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
-    "tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ],
-    "date": "2012-04-06",
-    "categories": [
-        "Development",
-        "VIM"
-    ],
-    "slug": "spf13-vim-3-0-release-and-new-website"
-}
-```
+{{</ code-toggle >}}
 
 ## Front Matter Variables
 
diff --git a/docs/content/content-management/image-processing/index.md b/docs/content/content-management/image-processing/index.md
index 1f84ba04d..ecc85bb51 100644
--- a/docs/content/content-management/image-processing/index.md
+++ b/docs/content/content-management/image-processing/index.md
@@ -23,7 +23,7 @@ The `image` is a [Page Resource]({{< relref "content-management/page-resources"
 To get all images in a [Page Bundle]({{< relref "content-management/organization#page-bundles" >}}):
 
 
-```html
+```go-html-template
 {{ with .Resources.ByType "image" }}
 {{ end }}
 
@@ -131,7 +131,7 @@ This is the shortcode used in the examples above:
 
 And it is used like this:
 
-```html
+```go-html-template
 {{</* imgproc sunset Resize "300x" /*/>}}
 ```
 
diff --git a/docs/content/content-management/menus.md b/docs/content/content-management/menus.md
index 1353ce0e2..c2eadf50f 100644
--- a/docs/content/content-management/menus.md
+++ b/docs/content/content-management/menus.md
@@ -118,9 +118,9 @@ menu:
 
 You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config].
 
-Here’s an example snippet pulled from a `config.toml`:
+Here’s an example snippet pulled from a configuration file:
 
-{{< code file="config.toml" >}}
+{{< code-toggle file="config.toml" >}}
 [[menu.main]]
     name = "about hugo"
     pre = "<i class='fa fa-heart'></i>"
@@ -132,23 +132,7 @@ Here’s an example snippet pulled from a `config.toml`:
     pre = "<i class='fa fa-road'></i>"
     weight = -100
     url = "/getting-started/"
-{{< /code >}}
-
-Here's the equivalent snippet in a `config.yaml`:
-
-{{< code file="config.yml" >}}
-menu:
-  main:
-      - name: "about hugo"
-        pre: "<i class='fa fa-heart'></i>"
-        weight: -110
-        identifier: "about"
-        url: "/about/"
-      - name: "getting started"
-        pre: "<i class='fa fa-road'></i>"
-        weight: -100
-        url: "/getting-started/"
-{{< /code >}}
+{{< /code-toggle >}}
 
 {{% note %}}
 The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`.
diff --git a/docs/content/content-management/multilingual.md b/docs/content/content-management/multilingual.md
index d27195a9a..28a6e4fec 100644
--- a/docs/content/content-management/multilingual.md
+++ b/docs/content/content-management/multilingual.md
@@ -21,9 +21,9 @@ You should define the available languages in a `languages` section in your site
 
 ## Configure Languages
 
-The following is an example of a TOML site configuration for a multilingual Hugo project:
+The following is an example of a site configuration for a multilingual Hugo project:
 
-{{< code file="config.toml" download="config.toml" >}}
+{{< code-toggle file="config" >}}
 DefaultContentLanguage = "en"
 copyright = "Everything is mine"
 
@@ -45,7 +45,7 @@ weight = 2
 linkedin = "lien-francais"
 [languages.fr.params.navigation]
 help  = "Aide"
-{{< /code >}}
+{{< /code-toggle >}}
 
 Anything not defined in a `[languages]` block will fall back to the global
 value for that key (e.g., `copyright` for the English [`en`] language).
@@ -92,7 +92,7 @@ This means that you can now configure a `baseURL` per `language`:
 
 Example:
 
-```bash
+{{< code-toggle file="config" >}}
 [languages]
 [languages.no]
 baseURL = "https://example.no"
@@ -105,7 +105,7 @@ baseURL = "https://example.com"
 languageName = "English"
 weight = 2
 title = "In English"
-```
+{{</ code-toggle >}}
 
 With the above, the two sites will be generated into `public` with their own root:
 
@@ -132,7 +132,7 @@ Live reload and `--navigateToChanged` between the servers work as expected.
 Taxonomies and [Blackfriday configuration][config] can also be set per language:
 
 
-{{< code file="bf-config.toml" >}}
+{{< code-toggle file="config" >}}
 [Taxonomies]
 tag = "tags"
 
@@ -152,7 +152,7 @@ weight = 2
 title = "Français"
 [languages.fr.Taxonomies]
 plaque = "plaques"
-{{< /code >}}
+{{</ code-toggle >}}
 
 ## Translate Your Content
 
diff --git a/docs/content/content-management/page-bundles.md b/docs/content/content-management/page-bundles.md
index 09aeae8ea..34620a5e2 100644
--- a/docs/content/content-management/page-bundles.md
+++ b/docs/content/content-management/page-bundles.md
@@ -93,7 +93,7 @@ anywhere:
 
 But you can get it by `.Site.GetPage`. Here is an example:
 
-```html
+```go-html-template
 {{ $headless := .Site.GetPage "page" "some-headless-bundle" }}
 {{ $reusablePages := $headless.Resources.Match "author*" }}
 <h2>Authors</h2>
diff --git a/docs/content/content-management/page-resources.md b/docs/content/content-management/page-resources.md
index f3b12d8c4..cefb1cd47 100644
--- a/docs/content/content-management/page-resources.md
+++ b/docs/content/content-management/page-resources.md
@@ -83,9 +83,9 @@ params
 : A map of custom key/values.
 
 
-###  Resources metadata: YAML Example
+###  Resources metadata example
 
-~~~yaml
+{{< code-toggle copy="false">}}
 title: Application
 date : 2018-01-25
 resources :
@@ -108,41 +108,7 @@ resources :
 - src : "**.docx"
   params :
     icon : "word"
-~~~
-
-###  Resources metadata: TOML Example
-
-~~~toml
-title = Application
-date : 2018-01-25
-[[resources]]
-  src = "images/sunset.jpg"
-  name = "header"
-[[resources]]
-  src = "documents/photo_specs.pdf"
-  title = "Photo Specifications"
-  [resources.params]
-    icon = "photo"
-[[resources]]
-  src = "documents/guide.pdf"
-  title = "Instruction Guide"
-[[resources]]
-  src = "documents/checklist.pdf"
-  title = "Document Checklist"
-[[resources]]
-  src = "documents/payment.docx"
-  title = "Proof of Payment"
-[[resources]]
-  src = "**.pdf"
-  name = "pdf-file-:counter"
-  [resources.params]
-    icon = "pdf"
-[[resources]]
-  src = "**.docx"
-  [resources.params]
-    icon = "word"
-~~~
-
+{{</ code-toggle >}}
 
 From the example above:
 
@@ -165,14 +131,14 @@ The counter starts at 1 the first time they are used in either `name` or `title`
 
 For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
 
-~~~toml
+{{< code-toggle copy="false">}}
 [[resources]]
   src = "*specs.pdf"
   title = "Specification #:counter"
 [[resources]]
   src = "**.pdf"
   name = "pdf-file-:counter"
-~~~
+{{</ code-toggle >}}
 
 the `Name` and `Title` will be assigned to the resource files as follows:
 
diff --git a/docs/content/content-management/related.md b/docs/content/content-management/related.md
index 8ae6e79ce..6f66e4468 100644
--- a/docs/content/content-management/related.md
+++ b/docs/content/content-management/related.md
@@ -34,6 +34,11 @@ To list up to 5 related pages is as simple as including something similar to thi
 {{ end }}
 {{< /code >}}
 
+
+{{% note %}}
+Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation more advanced usage of this feature.
+{{% /note %}}
+
 The full set of methods available on the page lists can bee seen in this Go interface:
 
 ```go
diff --git a/docs/content/content-management/static-files.md b/docs/content/content-management/static-files.md
index 12d27ccf2..fe5ea77e0 100644
--- a/docs/content/content-management/static-files.md
+++ b/docs/content/content-management/static-files.md
@@ -15,11 +15,11 @@ toc: true
 
 The `static` folder is where you place all your **static files**, e.g. stylesheets, JavaScript, images etc.
 
-You can set the name of the static folder to use in your configuration file, for example `config.toml`.  From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem.
+You can set the name of the static folder to use in your configuration file.  From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem.
 
 Example:
 
-```toml
+{{< code-toggle copy="false" file="config" >}}
 staticDir = ["static1", "static2"]
 [languages]
 [languages.no]
@@ -35,7 +35,7 @@ baseURL = "https://example.com"
 languageName = "English"
 weight = 2
 title = "In English"
-```
+{{</ code-toggle >}}
 
 In the above, with no theme used:
 
diff --git a/docs/content/content-management/syntax-highlighting.md b/docs/content/content-management/syntax-highlighting.md
index 67d443fd4..e7eb011c8 100644
--- a/docs/content/content-management/syntax-highlighting.md
+++ b/docs/content/content-management/syntax-highlighting.md
@@ -147,7 +147,7 @@ See [Highlight](/functions/highlight/).
 It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `pygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/);
 
 ````
-```html
+```go-html-template
 <section id="main">
   <div>
     <h1 id="title">{{ .Title }}</h1>
@@ -159,6 +159,11 @@ It is also possible to add syntax highlighting with GitHub flavored code fences.
 ```
 ````
 
+## List of Chroma Highlighting Languages
+
+The full list of Chroma lexers and their aliases (which is the identifier used in the `hightlight` template func or when doing highlighting in code fences):
+
+{{< chroma-lexers >}}
 
 ## Highlight with Pygments Classic
 
diff --git a/docs/content/content-management/taxonomies.md b/docs/content/content-management/taxonomies.md
index 1a59ebe3e..287c6f899 100644
--- a/docs/content/content-management/taxonomies.md
+++ b/docs/content/content-management/taxonomies.md
@@ -103,23 +103,14 @@ When taxonomies are used---and [taxonomy templates][] are provided---Hugo will a
 
 Taxonomies must be defined in your [website configuration][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
 
-### Example: TOML Taxonomy Configuration
+### Example: Taxonomy Configuration
 
-```
+{{< code-toggle copy="false" >}}
 [taxonomies]
   tag = "tags"
   category = "categories"
   series = "series"
-```
-
-### Example: YAML Taxonomy Configuration
-
-```
-taxonomies:
-  tag: "tags"
-  category: "categories"
-  series: "series"
-```
+{{</ code-toggle >}}
 
 ### Preserve Taxonomy Values
 
@@ -145,53 +136,16 @@ Assigning content to a taxonomy is done in the [front matter][]. Simply create a
 If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
 {{% /note %}}
 
-### Example: TOML Front Matter with Taxonomies
+### Example: Front Matter with Taxonomies
 
-```
-+++
+{{< code-toggle copy="false">}}
 title = "Hugo: A fast and flexible static site generator"
 tags = [ "Development", "Go", "fast", "Blogging" ]
 categories = [ "Development" ]
 series = [ "Go Web Dev" ]
 slug = "hugo"
 project_url = "https://github.com/gohugoio/hugo"
-+++
-```
-
-### Example: YAML Front Matter with Taxonomies
-
-```
----
-title: "Hugo: A fast and flexible static site generator"
-tags: ["Development", "Go", "fast", "Blogging"]
-categories: ["Development"]
-series: ["Go Web Dev"]
-slug: "hugo"
-project_url: "https://github.com/gohugoio/hugo"
----
-```
-
-### Example: JSON Front Matter with Taxonomies
-
-```
-{
-    "title": "Hugo: A fast and flexible static site generator",
-    "tags": [
-        "Development",
-        "Go",
-        "fast",
-        "Blogging"
-    ],
-    "categories" : [
-        "Development"
-    ],
-    "series" : [
-        "Go Web Dev"
-    ],
-    "slug": "hugo",
-    "project_url": "https://github.com/gohugoio/hugo"
-}
-```
+{{</ code-toggle >}}
 
 ## Order Taxonomies
 
@@ -199,29 +153,15 @@ A content file can assign weight for each of its associate taxonomies. Taxonomic
 
 The following TOML and YAML examples show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
 
-### Example: TOML Taxonomic `weight`
+### Example: Taxonomic `weight`
 
-```
-+++
+{{< code-toggle copy="false" >}}
 title = "foo"
 tags = [ "a", "b", "c" ]
 tags_weight = 22
 categories = ["d"]
 categories_weight = 44
-+++
-```
-
-### Example: YAML Taxonomic `weight`
-
-```
----
-title: foo
-tags: [ "a", "b", "c" ]