Merge commit 'f96384a3b596f9bc0a3a035970b09b2c601f0ccb'

4 files changed, 116 insertions, 283 deletions

diff --git a/docs/content/en/contribute/_index.md b/docs/content/en/contribute/_index.md
index 5e46ae287..cb6ca2966 100644
--- a/docs/content/en/contribute/_index.md
+++ b/docs/content/en/contribute/_index.md
@@ -2,20 +2,14 @@
 title: Contribute to the Hugo Project
 linktitle: Contribute to Hugo
 description: Contribute to Hugo development and documentation.
-date: 2017-02-01
-publishdate: 2017-02-01
-lastmod: 2017-02-01
 categories: [contribute]
 keywords: []
 menu:
   docs:
-    parent: "contribute"
+    parent: contribute
     weight: 01
-weight: 01	#rem
-draft: false
-slug:
+weight: 01
 aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/]
-toc: false
 ---
 
 Hugo relies heavily on the enthusiasm and participation of the open-source community. We need your support in both its development and documentation.
diff --git a/docs/content/en/contribute/development.md b/docs/content/en/contribute/development.md
index b11ef09de..c40b334ba 100644
--- a/docs/content/en/contribute/development.md
+++ b/docs/content/en/contribute/development.md
@@ -2,17 +2,13 @@
 title: Contribute to Hugo Development
 linktitle: Development
 description: Hugo relies heavily on contributions from the open source community.
-date: 2017-02-01
-publishdate: 2017-02-01
 categories: [contribute]
 keywords: [dev,open source]
-authors: [digitalcraftsman]
 menu:
   docs:
-    parent: "contribute"
+    parent: contribute
     weight: 10
 weight: 10
-sections_weight: 10
 toc: true
 ---
 
@@ -27,7 +23,7 @@ This contribution guide takes a step-by-step approach in hopes of helping newcom
 * You are new to Git or open-source projects in general
 * You are a fan of Hugo and enthusiastic about contributing to the project
 
-{{% note "Additional Questions?" %}}
+{{% note %}}
 If you're struggling at any point in this contribution guide, reach out to the Hugo community in [Hugo's Discussion forum](https://discourse.gohugo.io).
 {{% /note %}}
 
@@ -126,7 +122,9 @@ You set up the working copy of the repository locally on your computer. Your loc
 
 We assume that you've set up your `GOPATH` (see the section above if you're unsure about this). You should now copy the Hugo repository down to your computer. You'll hear this called "clone the repo". GitHub's [help pages](https://help.github.com/articles/cloning-a-repository/) give us a short explanation:
 
-> When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations.
+{{% note %}}
+When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations.
+{{% /note %}}
 
 We're going to clone the [master Hugo repository](https://github.com/gohugoio/hugo). That seems counter-intuitive, since you won't have commit rights on it. But it's required for the Go workflow. You'll work on a copy of the master and push your changes to your own repository on GitHub.
 
@@ -138,8 +136,7 @@ cd $HOME/src
 git clone https://github.com/gohugoio/hugo.git
 ```
 
-> Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build.
-> The easiest is to clone Hugo in a directory outside of GOPATH
+Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest is to clone Hugo in a directory outside of GOPATH
 
 And then, install dependencies of Hugo by running the following in the cloned directory:
 
@@ -158,7 +155,9 @@ go install github.com/magefile/mage@latest
 
 If you're not familiar with this term, GitHub's [help pages](https://help.github.com/articles/fork-a-repo/) provide again a simple explanation:
 
-> A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
+{{% note %}}
+A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
+{{% /note %}}
 
 #### Fork by hand
 
@@ -316,7 +315,7 @@ git commit --amend
 
 {{% warning "Be Careful Modifying Multiple Commits"%}}
 Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure!
-{{% /warning %}}
+{{% /note %}}
 
 This is a bit more advanced. Git allows you to [rebase](https://git-scm.com/docs/git-rebase) commits interactively. In other words: it allows you to rewrite the commit history.
 
@@ -421,7 +420,7 @@ Feel free to [open an issue][newissue] if you think you found a bug or you have
 [docscontrib]: /contribute/documentation/
 [forums]: https://discourse.gohugo.io
 [gitbook]: https://git-scm.com/
-[gobootcamp]: https://www.golangbootcamp.com/book/get_setup
+[gobootcamp]: https://www.golang-book.com/guides/machine_setup
 [godl]: https://go.dev/dl/
 [goinstall]: https://go.dev/doc/install
 [gvm]: https://github.com/moovweb/gvm
diff --git a/docs/content/en/contribute/documentation.md b/docs/content/en/contribute/documentation.md
index 641f86c81..b1fed4cb2 100644
--- a/docs/content/en/contribute/documentation.md
+++ b/docs/content/en/contribute/documentation.md
@@ -1,331 +1,176 @@
 ---
 title: Contribute to the Hugo Docs
 linktitle: Documentation
-description: Documentation is an integral part of any open source project. The Hugo docs are as much a work in progress as the source it attempts to cover.
-date: 2017-02-01
-publishdate: 2017-02-01
+description: Documentation is an integral part of any open source project. The Hugo documentation is as much a work in progress as the source it attempts to cover.
 categories: [contribute]
 keywords: [docs,documentation,community, contribute]
 menu:
   docs:
-    parent: "contribute"
+    parent: contribute
     weight: 20
+toc: true
 weight: 20
-sections_weight: 20
 aliases: [/contribute/docs/]
-toc: true
 ---
 
-## Create Your Fork
-
-It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of [hugoDocs](https://github.com/gohugoio/hugoDocs) on GitHub and cloned the repository locally on your machine. For more information, you can see [GitHub's documentation on "forking"][ghforking] or follow along with [Hugo's development contribution guide][hugodev].
-
-You can then create a separate branch for your additions. Be sure to choose a descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:
-
-```txt
-git checkout -b jon-doe-showcase-addition
-```
+## GitHub workflow
 
-## Add New Content
+Step 1
+: Fork the [documentation repository].
 
-The Hugo docs make heavy use of Hugo's [archetypes] feature. All content sections in Hugo documentation have an assigned archetype.
+Step 2
+: Clone your fork.
 
-Adding new content to the Hugo docs follows the same pattern, regardless of the content section:
+Step 3
+: Create a new branch with a descriptive name.
 
-```txt
-hugo new <DOCS-SECTION>/<new-content-lowercase>.md
+```bash
+git checkout -b fix/typos-site-variables
 ```
 
-### Add a New Function
-
-Once you have cloned the Hugo repository, you can create a new function via the following command. Keep the filename lowercase.
+Step 4
+: Make changes.
 
-```txt
-hugo new functions/newfunction.md
-```
+Step 5
+: Commit your changes with a descriptive commit message, typically 50 characters or less. Included the "Closes" keyword if your change addresses one or more open [issues].
 
-The archetype for `functions` according to the Hugo docs is as follows:
-
-{{< code file="archetypes/functions.md" >}}
-{{< readfile file="/archetypes/functions.md">}}
-{{< /code >}}
+```bash
+git commit -m "Fix typos on site variables page
 
-#### New Function Required Fields
-
-Here is a review of the front matter fields automatically generated for you using `hugo new functions/*`:
-
-***`title`***
-: this will be auto-populated in all lowercase when you use `hugo new` generator.
-
-***`linktitle`***
-: the function's actual casing (e.g., `replaceRE` rather than `replacere`).
-
-***`description`***
-: a brief description used to populate the [Functions Quick Reference](/functions/).
-
-`categories`
-: currently auto-populated with 'functions` for future-proofing and portability reasons only; ignore this field.
-
-`tags`
-: only if you think it will help end users find other related functions
-
-`signature`
-: this is a signature/syntax definition for calling the function (e.g., `apply SEQUENCE FUNCTION [PARAM...]`).
+Closes #1234
+Closes #5678"
+```
 
-`workson`
-: acceptable values include `lists`,`taxonomies`, `terms`, `groups`, and `files`.
+Step 5
+: Push the new branch to your fork of the documentation repository.
 
-`hugoversion`
-: the version of Hugo that will ship with this new function.
+Step 6
+: Visit the [documentation repository] and create a pull request (PR).
 
-`relatedfuncs`
-: other [templating functions] you feel are related to your new function to help fellow Hugo users.
+[documentation repository]: https://github.com/gohugoio/hugoDocs/
+[issues]: https://github.com/gohugoio/hugoDocs/issues
 
-`{{.Content}}`
-: an extended description of the new function; examples are not only welcomed but encouraged.
+Step 7
+: A project maintainer will review your PR, and may request changes. You may delete your branch after the maintainer merges your PR.
 
-In the body of your function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs [`code` shortcode](#add-code-blocks). If you are unable to add examples but would like to solicit help from the Hugo community, add `needsexample: true` to your front matter.
+## Including sample code
 
-## Add Code Blocks
+{{% note %}}
+Use this syntax to include shortcodes calls within your code samples:
 
-Code blocks are crucial for providing examples of Hugo's new features to end users of the Hugo docs. Whenever possible, create examples that you think Hugo users will be able to implement in their own projects.
+`{{</*/* foo */*/>}}`\
+`{{%/*/* foo */*/%}}`
+{{% /note %}}
 
-### Standard Syntax
+### Fenced code blocks
 
-Across many pages on the Hugo docs, the typical triple-back-tick Markdown syntax (```` ``` ````) is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard GitHub-flavored Markdown. 
+Include the language when using a fenced code block.
 
-````txt
+````text
 ```go-html-template
-{{ range site.RegularPages }}
-  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ if eq $foo "bar" }}
+  {{ print "foo is bar" }}
 {{ end }}
 ```
 ````
 
-
-### Code Block Shortcode
-
-The Hugo documentation comes with a very robust shortcode for adding interactive code blocks.
-
-{{% note %}}
-With the `code` shortcodes, *you must include triple back ticks and a language declaration*. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the Hugo docs.
-{{% /note %}}
-
-### `code`
-
-`code` is the Hugo docs shortcode you'll use most often. `code` requires has only one named parameter: `file`. Here is the pattern:
+Rendered:
 
 ```go-html-template
-{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
-A whole bunch of coding going on up in here!
-{{%/* /code */%}}
+{{ if eq $foo "bar" }}
+  {{ print "foo is bar" }}
+{{ end }}
 ```
 
-The following are the arguments passed into `code`:
+### The code shortcode
 
-***`file`***
-: the only *required* argument. `file` is needed for styling but also plays an important role in helping users create a mental model around Hugo's directory structure. Visually, this will be displayed as text in the top left of the code block.
+Use the `code` shortcode to include the file name and a copy-to-clipboard button. This shortcode accepts these optional parameters:
 
-`download`
-: if omitted, this will have no effect on the rendered shortcode. When a value is added to `download`, it's used as the filename for a downloadable version of the code block.
+copy
+: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `true`.
 
-`copy`
-: a copy button is added automatically to all `code` shortcodes. If you want to keep the filename and styling of `code` but don't want to encourage readers to copy the code (e.g., a "Do not do" snippet in a tutorial), use `copy="false"`.
+file
+: (`string`) The file name to display. If you do not provide a `lang` parameter, the file extension determines the code language.
 
-#### Example `code` Input
+lang
+: (`string`) The code language. Default is `text`.
 
-This example HTML code block tells Hugo users the following:
-
-1. This file *could* live in `layouts/_default`, as demonstrated by `layouts/_default/single.html` as the value for `file`.
-2. This snippet is complete enough to be downloaded and implemented in a Hugo project, as demonstrated by `download="single.html"`.
-
-```go-html-template
-{{</* code file="layouts/_default/single.html" download="single.html" */>}}
-{{ define "main" }}
-<main>
-    <article>
-        <header>
-            <h1>{{.Title}}</h1>
-            {{with .Params.subtitle}}
-            <span>{{.}}</span>
-        </header>
-        <div>
-            {{.Content}}
-        </div>
-        <aside>
-            {{.TableOfContents}}
-        </aside>
-    </article>
-</main>
+````text
+{{</* code file="layouts/_default_/single.html" */>}}
+{{ if eq $foo "bar" }}
+  {{ print "foo is bar" }}
 {{ end }}
 {{</* /code */>}}
-```
 
-##### Example 'code' Display
-
-The output of this example will render to the Hugo docs as follows:
-
-{{< code file="layouts/_default/single.html" download="single.html" >}}
-{{ define "main" }}
-<main>
-    <article>
-        <header>
-            <h1>{{.Title}}</h1>
-            {{with .Params.subtitle}}
-            <span>{{.}}</span>
-        </header>
-        <div>
-            {{.Content}}
-        </div>
-        <aside>
-            {{.TableOfContents}}
-        </aside>
-    </article>
-</main>
+````
+
+Rendered:
+
+{{< code file="layouts/_default_/single.html" >}}
+{{ if eq $foo "bar" }}
+  {{ print "foo is bar" }}
 {{ end }}
 {{< /code >}}
 
-<!-- #### Output Code Block
+### The code-toggle shortcode
 
-The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode:
+Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. This shortcode accepts these optional parameters:
 
-```
-{{%/* output file="posts/my-first-post/index.html" */%}}
-<h1>This is my First Hugo Blog Post</h1>
-<p>I am excited to be using Hugo.</p>
-{{%/* /output */%}}
-```
+copy
+: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `true`.
 
-The preceding `output` example will render as follows to the Hugo docs:
+file
+: (`string`) The file name to display. Omit the file extension for site configuration and data file examples.
 
-{{< output file="posts/my-first-post/index.html" >}}
-<h1>This is my First Hugo Blog Post</h1>
-<p>I am excited to be using Hugo.</p>
-{{< /output >}} -->
+fm
+: (`bool`) If `true`, displays the code as front matter. Default is `false`.
 
-## Blockquotes
+#### Site configuration example
 
-Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]:
-
-```md
-> Without the threat of punishment, there is no joy in flight.
+```text
+{{</* code-toggle file="config" */>}}
+baseURL = 'https://example.org'
+languageCode = 'en-US'
+title = "Example Site"
+{{</* /code-toggle */>}}
 ```
 
-The preceding blockquote will render as follows in the Hugo docs:
+Rendered:
 
-> Without the threat of punishment, there is no joy in flight.
+{{< code-toggle file="config" >}}
+baseURL = 'https://example.org'
+languageCode = 'en-US'
+title = "Example Site"
+{{< /code-toggle >}}
 
-However, you can add a quick and easy `<cite>` element (added on the client via JavaScript) by separating your main blockquote and the citation with a hyphen with a single space on each side:
+#### Front matter example
 
-```md
-> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)
+```text
+{{</* code-toggle file="content/about.md" fm=true */>}}
+title = "About"
+date = 2023-04-02T12:47:24-07:00
+draft = false
+{{</* /code-toggle */>}}
 ```
 
-Which will render as follows in the Hugo docs:
-
-> Without the threat of punishment, there is no joy in flight. - [Kobo Abe][abe]
+Rendered:
 
-{{% note "Blockquotes `!=` Admonitions" %}}
-Previous versions of Hugo documentation used blockquotes to draw attention to text. This is *not* the [intended semantic use of `<blockquote>`](https://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting. To note or warn your user of specific information, use the admonition shortcodes that follow.
-{{% /note %}}
+{{< code-toggle file="content/about.md" fm=true >}}
+title = "About"
+date = 2023-04-02T12:47:24-07:00
+draft = false
+{{< /code-toggle >}}
 
 ## Admonitions
 
-**Admonitions** are common in technical documentation. The most popular is that seen in [reStructuredText Directives][sourceforge]. From the SourceForge documentation:
-
-> Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - [SourceForge][sourceforge]
-
-The Hugo docs contain three admonitions: `note`, `tip`, and `warning`.
+Use the `note` shortcode to draw attention to content. Use the `{{%/*  */%}}` notation when calling this shortcode.
 
-### `note` Admonition
-
-Use the `note` shortcode when you want to draw attention to information subtly. `note` is intended to be less of an interruption in content than is `warning`.
-
-#### Example `note` Input
-
-{{< code file="note-with-heading.md" >}}
+```text
 {{%/* note */%}}
-Here is a piece of information I would like to draw your **attention** to.
+This is **bold** text.
 {{%/* /note */%}}
-{{< /code >}}
-
-#### Example `note` Output
-
-{{< output file="note-with-heading.html" >}}
-{{% note %}}
-Here is a piece of information I would like to draw your **attention** to.
-{{% /note %}}
-{{< /output >}}
-
-#### Example `note` Display
+```
 
 {{% note %}}
-Here is a piece of information I would like to draw your **attention** to.
-{{% /note %}}
-
-### `tip` Admonition
-
-Use the `tip` shortcode when you want to give the reader advice. `tip`, like `note`, is intended to be less of an interruption in content than is `warning`.
-
-#### Example `tip` Input
-
-{{< code file="using-tip.md" >}}
-{{%/* tip */%}}
-Here's a bit of advice to improve your productivity with Hugo.
-{{%/* /tip */%}}
-{{< /code >}}
-
-#### Example `tip` Output
-
-{{< output file="tip-output.html" >}}
-{{% tip %}}
-Here's a bit of advice to improve your productivity with Hugo.
-{{% /tip %}}
-{{< /output >}}
-
-#### Example `tip` Display
-
-{{% tip %}}
-Here's a bit of advice to improve your productivity with Hugo.
-{{% /tip %}}
-
-### `warning` Admonition
-
-Use the `warning` shortcode when you want to draw the user's attention to something important. A good usage example is for articulating breaking changes in Hugo versions, known bugs, or templating "gotchas."
-
-#### Example `warning` Input
-
-{{< code file="warning-admonition-input.md" >}}
-{{%/* warning */%}}
-This is a warning, which should be reserved for *important* information like breaking changes.
-{{%/* /warning */%}}
-{{< /code >}}
-
-#### Example `warning` Output
-
-{{< output file="warning-admonition-output.html" >}}
-{{% warning %}}
-This is a warning, which should be reserved for *important* information like breaking changes.
-{{% /warning %}}
-{{< /output >}}
-
-#### Example `warning` Display
-
-{{% warning %}}
-This is a warning, which should be reserved for *important* information like breaking changes.
-{{% /warning %}}
-
-{{% note "Pull Requests and Branches" %}}
-Similar to [contributing to Hugo development](/contribute/development/), the Hugo team expects you to create a separate branch/fork when you make your contributions to the Hugo docs.
+This is **bold** text.
 {{% /note %}}
-
-[abe]: https://en.wikipedia.org/wiki/Kobo_Abe
-[archetypes]: /content-management/archetypes/
-[bqsyntax]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes
-[charcount]: https://www.lettercount.com/
-[`docs/static/images/showcase/`]: https://github.com/gohugoio/hugo/tree/master/docs/static/images/showcase/
-[ghforking]: https://help.github.com/articles/fork-a-repo/
-[hugodev]: /contribute/development/
-[shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
-[sourceforge]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions
-[templating function]: /functions/
diff --git a/docs/content/en/contribute/themes.md b/docs/content/en/contribute/themes.md
index c515d1fcf..adfc38cc2 100644
--- a/docs/content/en/contribute/themes.md
+++ b/docs/content/en/contribute/themes.md
@@ -2,19 +2,14 @@
 title: Add Your Hugo Theme to the Showcase
 linktitle: Themes
 description: If you've built a Hugo theme and want to contribute back to the Hugo Community, share it with us.
-date: 2017-02-01
-publishdate: 2017-02-01
 categories: [contribute]
 keywords: [contribute,themes,design]
-authors: [digitalcraftsman]
 menu:
   docs:
-    parent: "contribute"
+    parent: contribute
     weight: 30
 weight: 30
-sections_weight: 30
 aliases: [/contribute/theme/]
-wip: true
 toc: true
 ---