Replace output shortcode calls

content/en/content-management/shortcodes.md

@@ -125,130 +125,129 @@ attrlink
 #### Example `figure` Input
 
 {{< code file="figure-input-example.md" >}}
-{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
+{{</* figure src="elephant.jpg" title=">An elephant at sunset" */>}}
 {{< /code >}}
 
 #### Example `figure` Output
 
-{{< output file="figure-output-example.html" >}}
+```html
 <figure>
-  <img src="/media/spf13.jpg"  />
+  <img src="elephant.jpg">
-  <figcaption>
+  <figcaption>An elephant at sunset</figcaption>
-      <h4>Steve Francia</h4>
-  </figcaption>
 </figure>
-{{< /output >}}
+```
 
 ### `gist`
 
-Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]:
+To display a GitHub [gist] with this URL:
 
-```txt
+[gist]: https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists
-https://gist.github.com/spf13/7896402
+
+```text
+https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
 ```
 
-We can embed the gist in our content via username and gist ID pulled from the URL:
+Include this in your markdown:
 
-```go-html-template
+```text
-{{</* gist spf13 7896402 */>}}
+{{</* gist user 50a7482715eac222e230d1e64dd9a89b */>}}
 ```
 
-#### Example `gist` Input
+This will display all files in the gist alphabetically by file name.
 
-If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument:
+{{< gist jmooring 50a7482715eac222e230d1e64dd9a89b >}}
 
-{{< code file="gist-input.md" >}}
+To display a specific file within the gist:
-{{</* gist spf13 7896402 "img.html" */>}}
-{{< /code >}}
 
-#### Example `gist` Output
+```text
+{{</* gist user 50a7482715eac222e230d1e64dd9a89b 1-template.html */>}}
+```
 
-{{< output file="gist-output.html" >}}
+Rendered:
-{{< gist spf13 7896402 >}}
-{{< /output >}}
 
-#### Example `gist` Display
+{{< gist jmooring 50a7482715eac222e230d1e64dd9a89b 1-template.html >}}
-
-To demonstrate the remarkable efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will depend on your stylesheets and surrounding markup.
-
-{{< gist spf13 7896402 >}}
 
 ### `highlight`
 
-This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/content-management/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode.
+To display a highlighted code sample:
 
-#### Example `highlight` Input
+```text
-
+{{</* highlight go-html-template */>}}
-{{< code file="content/tutorials/learn-html.md" >}}
+{{ range .Pages }}
-{{</* highlight html */>}}
+  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
-<section id="main">
+{{ end }}
-  <div>
-   <h1 id="title">{{ .Title }}</h1>
-    {{ range .Pages }}
-        {{ .Render "summary" }}
-    {{ end }}
-  </div>
-</section>
 {{</* /highlight */>}}
-{{< /code >}}
+```
 
-#### Example `highlight` Output
+Rendered:
 
-The `highlight` shortcode example above would produce the following HTML when the site is rendered:
+{{< highlight go-html-template >}}
+{{ range .Pages }}
+  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{< /highlight >}}
 
-{{< output file="tutorials/learn-html/index.html" >}}
+To specify one or more [highlighting options], include a quotation-encapsulated, comma-separated list:
-<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
-  <span style="color: #f92672">&lt;div&gt;</span>
-   <span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
-    {{ range .Pages }}
-        {{ .Render &quot;summary&quot;}}
-    {{ end }}
-  <span style="color: #f92672">&lt;/div&gt;</span>
-<span style="color: #f92672">&lt;/section&gt;</span>
-{{< /output >}}
 
-{{% note "More on Syntax Highlighting" %}}
+[highlighting options]: /functions/highlight/
-To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting in Developer Tools](/content-management/syntax-highlighting/).
+
-{{% /note %}}
+```text
+{{</* highlight go-html-template "lineNos=inline, lineNoStart=42" */>}}
+{{ range .Pages }}
+  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{</* /highlight */>}}
+```
+
+Rendered:
+
+{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}}
+{{ range .Pages }}
+  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{< /highlight >}}
 
 ### `instagram`
 
-If you'd like to embed a photo from [Instagram], you only need the photo's ID. You can discern an Instagram photo ID from the URL:
+The `instagram` shortcode uses Facebook's **oEmbed Read** feature. The  Facebook [developer documentation] states:
 
-```txt
+- This permission or feature requires successful completion of the App Review process before your app can access live data. [Learn More]
+- This permission or feature is only available with business verification. You may also need to sign additional contracts before your app can access data. [Learn More Here]s
+
+[developer documentation]: https://developers.facebook.com/docs/features-reference/oembed-read
+[Learn More]: https://developers.facebook.com/docs/app-review
+[Learn More Here]: https://developers.facebook.com/docs/development/release/business-verification
+
+You must obtain an Access Token to use the `instagram` shortcode.
+
+If your site configuration is private:
+
+{{< code-toggle file=config copy=false >}}
+[services.instagram]
+accessToken = 'xxx'
+{{< /code-toggle >}}
+
+If your site configuration is _not_ private, set the Access Token with an environment variable:
+
+```text
+HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify
+```
+
+{{% note %}}
+If you are using a Client Access Token, you must combine the Access Token with your App ID using a pipe symbol (`APPID|ACCESSTOKEN`).
+{{% /note %}}
+
+To display an Instagram post with this URL:
+
+```text
 https://www.instagram.com/p/BWNjjyYFxVx/
 ```
 
-#### Example `instagram` Input
+Include this in your markdown:
 
-{{< code file="instagram-input.md" >}}
+```text
 {{</* instagram BWNjjyYFxVx */>}}
-{{< /code >}}
+```
-
-You also have the option to hide the caption:
-
-{{< code file="instagram-input-hide-caption.md" >}}
-{{</* instagram BWNjjyYFxVx hidecaption */>}}
-{{< /code >}}
-
-#### Example `instagram` Output
-
-By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup:
-
-{{< output file="instagram-hide-caption-output.html" >}}
-{{< instagram BWNjjyYFxVx hidecaption >}}
-{{< /output >}}
-
-#### Example `instagram` Display
-
-Using the preceding `instagram` with `hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your style sheets and surrounding markup.
-
-{{< instagram BWNjjyYFxVx hidecaption >}}
-
-
-{{% note %}}
-The `instagram`-shortcode refers an endpoint of Instagram's API, that's deprecated since October 24th, 2020. Thus, no images can be fetched from this API endpoint, resulting in an error when the `instagram`-shortcode is used. For more information please have a look at GitHub issue [#7879](https://github.com/gohugoio/hugo/issues/7879).
-{{% /note %}}
 
 ### `param`
 
@@ -298,57 +297,39 @@ Assuming that standard Hugo pretty URLs are turned on.
 
 ### `tweet`
 
-You want to include a single tweet into your blog post? Everything you need is the URL of the tweet:
+To display a Twitter post with this URL:
 
 ```txt
 https://twitter.com/SanDiegoZoo/status/1453110110599868418
 ```
 
-#### Example `tweet` Input
+Include this in your markdown:
 
-Pass the tweet's user (case-insensitive) and ID from the URL as parameters to the `tweet` shortcode.
+```text
-
-{{< code file="example-tweet-input.md" >}}
 {{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
-{{< /code >}}
+```
 
-#### Example `tweet` Output
+Rendered:
-
-Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup:
-
-{{< output file="example-tweet-output.html" >}}
-{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
-{{< /output >}}
-
-#### Example `tweet` Display
-
-Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
 
 {{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}
 
 ### `vimeo`
 
-Adding a video from [Vimeo] is equivalent to the [YouTube Input shortcode].
+To display a Vimeo video with this URL:
 
-```txt
+```text
-https://vimeo.com/channels/staffpicks/146022717
+https://vimeo.com/channels/staffpicks/55073825
 ```
 
-#### Example `vimeo` Input
+Include this in your markdown:
 
-Extract the ID from the video's URL and pass it to the `vimeo` shortcode:
+```text
+{{</* vimeo 55073825 */>}}
+```
 
-{{< code file="example-vimeo-input.md" >}}
+Rendered:
-{{</* vimeo 146022717 */>}}
-{{< /code >}}
 
-#### Example `vimeo` Output
+{{< vimeo 55073825 >}}
-
-Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup:
-
-{{< output file="example-vimeo-output.html" >}}
-{{< vimeo 146022717 >}}
-{{< /output >}}
 
 {{% note %}}
 If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named parameter as well. You can also give the vimeo video a descriptive title with `title`.
@@ -358,12 +339,6 @@ If you want to further customize the visual styling of the YouTube or Vimeo outp
 ```
 {{% /note %}}
 
-#### Example `vimeo` Display
-
-Using the preceding `vimeo` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup.
-
-{{< vimeo 146022717 >}}
-
 ### `youtube`
 
 The `youtube` shortcode embeds a responsive video player for [YouTube videos]. Only the ID of the video is required, e.g.:

content/en/functions/base64.md

@@ -10,23 +10,9 @@ relatedfuncs: []
 signature: ["base64Decode INPUT", "base64Encode INPUT"]
 ---
 
-An example:
-
-{{< code file="base64-input.html" >}}
-<p>Hello world = {{ "Hello world" | base64Encode }}</p>
-<p>SGVsbG8gd29ybGQ = {{ "SGVsbG8gd29ybGQ=" | base64Decode }}</p>
-{{< /code >}}
-
-{{< output file="base-64-output.html" >}}
-<p>Hello world = SGVsbG8gd29ybGQ=</p>
-<p>SGVsbG8gd29ybGQ = Hello world</p>
-{{< /output >}}
-
-You can also pass other data types as arguments to the template function which tries to convert them. The following will convert *42* from an integer to a string because both `base64Encode` and `base64Decode` always return a string.
-
 ```go-html-template
-{{ 42 | base64Encode | base64Decode }}
+{{ "Hugo" | base64Encode }} → "SHVnbw=="
-=> "42" rather than 42
+{{ "SHVnbw==" | base64Decode }} → "Hugo"
 ```
 
 ## `base64` with APIs

content/en/functions/default.md

@@ -35,18 +35,18 @@ newparam:
 `default` can be written in more than one way:
 
 ```go-html-template
-{{ index .Params "font" | default "Roboto" }}
+{{ .Params.font | default "Roboto" }}
-{{ default "Roboto" (index .Params "font") }}
+{{ default "Roboto" .Params.font }}
 ```
 
 Both of the above `default` function calls return `Roboto`.
 
 A `default` value, however, does not need to be hard coded like the previous example. The `default` value can be a variable or pulled directly from the front matter using dot notation:
 
-{{< code file="variable-as-default-value.html" copy=false >}}
+```go-html-template
 {{ $old := .Params.oldparam }}
 <p>{{ .Params.newparam | default $old }}</p>
-{{< /code >}}
+```
 
 Which would return:
 
@@ -56,28 +56,28 @@ Which would return:
 
 And then using dot notation
 
-{{< code file="dot-notation-default-value.html" >}}
+```go-html-template
 <title>{{ .Params.seo_title | default .Title }}</title>
-{{< /code >}}
+```
 
 Which would return
 
-{{< output file="dot-notation-default-return-value.html" >}}
+```html
 <title>Sane Defaults</title>
-{{< /output >}}
+```
 
 The following have equivalent return values but are far less terse. This demonstrates the utility of `default`:
 
 Using `if`:
 
-{{< code file="if-instead-of-default.html" copy=false >}}
+```go-html-template
 <title>{{ if .Params.seo_title }}{{ .Params.seo_title }}{{ else }}{{ .Title }}{{ end }}</title>
 => Sane Defaults
-{{< /code >}}
+```
 
 Using `with`:
 
-{{< code file="with-instead-of-default.html" copy=false >}}
+```go-html-template
 <title>{{ with .Params.seo_title }}{{ . }}{{ else }}{{ .Title }}{{ end }}</title>
 => Sane Defaults
-{{< /code >}}
+```

content/en/functions/delimit.md

@@ -6,46 +6,26 @@ menu:
   docs:
     parent: functions
 keywords: [iteration]
-signature: ["delimit COLLECTION DELIMIT LAST"]
+signature: ["delimit COLLECTION DELIMITER [LAST]"]
 relatedfuncs: []
 ---
 
-`delimit` called in your template takes the form of
+Delimit a slice:
 
 ```go-html-template
-{{ delimit array/slice/map delimiter optionallastdelimiter }}
+{{ $s := slice "b" "a" "c" }}
+{{ delimit $s ", " }} → "b, a, c"
+{{ delimit $s ", " " and "}} → "b, a and c"
 ```
 
-`delimit` loops through any array, slice, or map and returns a string of all the values separated by a delimiter, the second argument in the function call. There is an optional third parameter that lets you choose a different delimiter to go between the last two values in the loop.
+Delimit a map:
 
-To maintain a consistent output order, maps will be sorted by keys and only a slice of the values will be returned.
+{{% note %}}
+The `delimit` function sorts maps by key, returning the values.
+{{% /note %}}
 
-The examples of `delimit` that follow all use the same front matter:
+```go-html-template
-
+{{ $m := dict "b" 2 "a" 1 "c" 3 }}
-{{< code-toggle file="content/about.md" copy=false fm=true >}}
+{{ delimit $m ", " }} → "1, 2, 3"
-title: About
+{{ delimit $m ", " " and "}} → "1, 2 and 3"
-tags: [ "tag1", "tag2", "tag3" ]
+```
-{{< /code-toggle >}}
-
-{{< code file="delimit-page-tags-input.html" >}}
-<p>Tags: {{ delimit .Params.tags ", " }}</p>
-{{< /code >}}
-
-{{< output file="delimit-page-tags-output.html" >}}
-<p>Tags: tag1, tag2, tag3</p>
-{{< /output >}}
-
-Here is the same example but with the optional "last" delimiter:
-
-{{< code file="delimit-page-tags-final-and-input.html" >}}
-Tags: {{ delimit .Params.tags ", " ", and " }}
-{{< /code >}}
-
-{{< output file="delimit-page-tags-final-and-output.html" >}}
-<p>Tags: tag1, tag2, and tag3</p>
-{{< /output >}}
-
-
-[lists]: /templates/lists/
-[taxonomies]: /templates/taxonomy-templates/#taxonomy-list-templates
-[terms]: /templates/taxonomy-templates/#terms-list-templates

content/en/functions/safeURL.md

@@ -16,11 +16,11 @@ Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are cons
 
 The following examples use a [site `config.toml`][configuration] with the following [menu entry][menus]:
 
-{{< code file="config.toml" copy=false >}}
+{{< code-toggle file="config" copy=false >}}
 [[menu.main]]
-    name = "IRC: #golang at freenode"
+name = "IRC: #golang at freenode"
-    url = "irc://irc.freenode.net/#golang"
+url = "irc://irc.freenode.net/#golang"
-{{< /code >}}
+{{< /code-toggle >}}
 
 The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
 
@@ -28,19 +28,19 @@ The following is an example of a sidebar partial that may be used in conjunction
 <!-- This unordered list may be part of a sidebar menu -->
 <ul>
   {{ range .Site.Menus.main }}
-  <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+    <li><a href="{{ .URL }}">{{ .Name }}</a></li>
   {{ end }}
 </ul>
 {{< /code >}}
 
 This partial would produce the following HTML output:
 
-{{< output file="bad-url-sidebar-menu-output.html" >}}
+```html
 <!-- This unordered list may be part of a sidebar menu -->
 <ul>
-    <li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
+  <li><a href="#ZgotmplZ">IRC: #golang at freenode</a></li>
 </ul>
-{{< /output >}}
+```
 
 The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable:
 
@@ -53,11 +53,11 @@ The odd output can be remedied by adding ` | safeURL` to our `.URL` page variabl
 
 With the `.URL` page variable piped through `safeURL`, we get the desired output:
 
-{{< output file="correct-url-sidebar-menu-output.html" >}}
+```html
 <ul class="sidebar-menu">
-    <li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
+  <li><a href="irc://irc.freenode.net/#golang">IRC: #golang at freenode</a></li>
 </ul>
-{{< /output >}}
+```
 
 [configuration]: /getting-started/configuration/
 [menus]: /content-management/menus/

content/en/functions/shuffle.md

@@ -10,20 +10,10 @@ signature: ["shuffle COLLECTION"]
 relatedfuncs: [seq]
 ---
 
-{{< code file="shuffle-input.html" >}}
-<!-- Shuffled sequence = -->
-<div>{{ shuffle (seq 1 5) }}</div>
-<!-- Shuffled slice =  -->
-<div>{{ shuffle (slice "foo" "bar" "buzz") }}</div>
-{{< /code >}}
 
-This example would return the following:
+```go-html-template
+{{ shuffle (seq 1 2 3) }} → [3 1 2] 
+{{ shuffle (slice "a" "b" "c") }} → [b a c] 
+```
 
-{{< output file="shuffle-output.html" >}}
+The result will vary from one build to the next.
-<!-- Shuffled sequence =  -->
-<div>2 5 3 1 4</div>
-<!-- Shuffled slice =  -->
-<div>buzz foo bar</div>
-{{< /output >}}
-
-This example also makes use of the [slice](/functions/slice/) and [seq](/functions/seq/) functions.

content/en/functions/urlize.md

@@ -39,24 +39,24 @@ The following might be used as a partial within a [single page template][singlet
 </header>
 {{< /code >}}
 
-The preceding partial would then output to the rendered page as follows, assuming the page is being built with Hugo's default pretty URLs.
+The preceding partial would then output to the rendered page as follows:
 
-{{< output file="/blog/greatest-city/index.html" >}}
+```html
 <header>
-    <h1>The World&#39;s Greatest City</h1>
+  <h1>The World&#39;s Greatest City</h1>
-    <div><a href="/locations/chicago-il">Chicago IL</a></div>
+  <div><a href="/locations/chicago-il">Chicago IL</a></div>
-    <ul>
+  <ul>
-        <li>
+    <li>
-            <a href="/tags/pizza">pizza</a>
+      <a href="/tags/pizza">pizza</a>
-        </li>
+    </li>
-        <li>
+    <li>
-            <a href="/tags/beer">beer</a>
+      <a href="/tags/beer">beer</a>
-        </li>
+    </li>
-        <li>
+    <li>
-            <a href="/tags/hot-dogs">hot dogs</a>
+      <a href="/tags/hot-dogs">hot dogs</a>
-        </li>
+    </li>
-    </ul>
+  </ul>
 </header>
-{{< /output >}}
+```
 
 [singletemplate]: /templates/single-page-templates/

content/en/variables/page.md

@@ -264,11 +264,7 @@ With the above front matter, the `tags` and `categories` taxonomies are accessib
 * `.Params.tags`
 * `.Params.categories`
 
-{{% note "Casing of Params" %}}
+The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter:
-Page-level `.Params` are *only* accessible in lowercase.
-{{% /note %}}
-
-The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`:
 
 {{< code-toggle file="content/example.md" fm=true copy=false >}}
 title: Example
@@ -276,21 +272,19 @@ affiliatelink: "http://www.my-book-link.here"
 recommendedby: "My Mother"
 {{< /code-toggle >}}
 
-These fields would then be accessible to the `/themes/yourtheme/layouts/review/single.html` template through `.Params.affiliatelink` and `.Params.recommendedby`, respectively.
+These fields would then be accessible to via `.Params.affiliatelink` and `.Params.recommendedby`.
 
-Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors.
+```go-html-template
-
+<h3><a href="{{ .Params.affiliatelink }}">Buy this book</a></h3>
-{{< code file="/themes/yourtheme/layouts/review/single.html" >}}
-<h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
 <p>It was recommended by {{ .Params.recommendedby }}.</p>
-{{< /code >}}
+```
 
-This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/):
+This template would render as follows:
 
-{{< output file="yourbaseurl/review/book01/index.html" >}}
+```html
 <h3><a href="http://www.my-book-link.here">Buy this book</a></h3>
 <p>It was recommended by my Mother.</p>
-{{< /output >}}
+```
 
 {{% note %}}
 See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content.

layouts/shortcodes/output.html

@@ -1,8 +0,0 @@
-{{$file := .Get "file"}}
-{{$icon := index (split $file ".") 1 }}
-<div class="code" id="{{$file | urlize}}">
-	<div class="filename" title="{{$file}}">{{$file}}</div>
-	<div class="code-copy-content output-content">
-	<pre><code>{{- .Inner | string -}}</code></pre>
-	</div>
-</div>