TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-08 09:14:52 -04:00
Code Issues Packages Projects Releases Wiki Activity

Replace output shortcode calls

Browse Source
This commit is contained in:
Joe Mooring 2023-04-03 11:26:06 -07:00 committed by Joe Mooring
parent 0c66fb055c
commit 944e274304
9 changed files with 167 additions and 250 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

223
content/en/content-management/shortcodes.md
View File

@ -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" />
<figcaption>
<h4>Steve Francia</h4>
</figcaption>
<img src="elephant.jpg">
<figcaption>An elephant at sunset</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
https://gist.github.com/spf13/7896402
[gist]: https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists
```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
{{</* gist spf13 7896402 */>}}
```text
{{</* 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" >}}
{{</* gist spf13 7896402 "img.html" */>}}
{{< /code >}}
To display a specific file within the gist:
#### Example `gist` Output
```text
{{</* gist user 50a7482715eac222e230d1e64dd9a89b 1-template.html */>}}
```
{{< output file="gist-output.html" >}}
{{< gist spf13 7896402 >}}
{{< /output >}}
Rendered:
#### Example `gist` Display
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 >}}
{{< gist jmooring 50a7482715eac222e230d1e64dd9a89b 1-template.html >}}
### `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
{{< code file="content/tutorials/learn-html.md" >}}
{{</* highlight html */>}}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Pages }}
{{ .Render "summary" }}
{{ end }}
</div>
</section>
```text
{{</* highlight go-html-template */>}}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}
{{</* /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" >}}
<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 >}}
To specify one or more [highlighting options], include a quotation-encapsulated, comma-separated list:
{{% note "More on Syntax Highlighting" %}}
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 %}}
[highlighting options]: /functions/highlight/
```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.
{{< code file="example-tweet-input.md" >}}
```text
{{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
{{< /code >}}
```
#### Example `tweet` Output
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.
Rendered:
{{< 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
https://vimeo.com/channels/staffpicks/146022717
```text
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" >}}
{{</* vimeo 146022717 */>}}
{{< /code >}}
Rendered:
#### Example `vimeo` Output
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 >}}
{{< vimeo 55073825 >}}
{{% 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.:

18
content/en/functions/base64.md
View File

@ -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 }}
=> "42" rather than 42
{{ "Hugo" | base64Encode }} → "SHVnbw=="
{{ "SHVnbw==" | base64Decode }} → "Hugo"
```
## `base64` with APIs

24
content/en/functions/default.md
View File

@ -35,18 +35,18 @@ newparam:
`default` can be written in more than one way:
```go-html-template
{{ index .Params "font" | default "Roboto" }}
{{ default "Roboto" (index .Params "font") }}
{{ .Params.font | default "Roboto" }}
{{ 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 >}}
```

48
content/en/functions/delimit.md
View File

@ -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:
{{< code-toggle file="content/about.md" copy=false fm=true >}}
title: About
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
```go-html-template
{{ $m := dict "b" 2 "a" 1 "c" 3 }}
{{ delimit $m ", " }} → "1, 2, 3"
{{ delimit $m ", " " and "}} → "1, 2 and 3"
```

22
content/en/functions/safeURL.md
View File

@ -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"
url = "irc://irc.freenode.net/#golang"
{{< /code >}}
name = "IRC: #golang at freenode"
url = "irc://irc.freenode.net/#golang"
{{< /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/

20
content/en/functions/shuffle.md
View File

@ -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" >}}
<!-- 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.
The result will vary from one build to the next.

32
content/en/functions/urlize.md
View File

@ -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>
<div><a href="/locations/chicago-il">Chicago IL</a></div>
<ul>
<li>
<a href="/tags/pizza">pizza</a>
</li>
<li>
<a href="/tags/beer">beer</a>
</li>
<li>
<a href="/tags/hot-dogs">hot dogs</a>
</li>
</ul>
<h1>The World&#39;s Greatest City</h1>
<div><a href="/locations/chicago-il">Chicago IL</a></div>
<ul>
<li>
<a href="/tags/pizza">pizza</a>
</li>
<li>
<a href="/tags/beer">beer</a>
</li>
<li>
<a href="/tags/hot-dogs">hot dogs</a>
</li>
</ul>
</header>
{{< /output >}}
```
[singletemplate]: /templates/single-page-templates/

22
content/en/variables/page.md
View File

@ -264,11 +264,7 @@ With the above front matter, the `tags` and `categories` taxonomies are accessib
* `.Params.tags`
* `.Params.categories`
{{% note "Casing of Params" %}}
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`:
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:
{{< 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.
{{< code file="/themes/yourtheme/layouts/review/single.html" >}}
<h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
```go-html-template
<h3><a href="{{ .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.

8
layouts/shortcodes/output.html
View File

@ -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>