diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md index 783c83616..131ae3ca6 100644 --- a/content/en/content-management/shortcodes.md +++ b/content/en/content-management/shortcodes.md @@ -125,130 +125,129 @@ attrlink #### Example `figure` Input {{< code file="figure-input-example.md" >}} -{{}} +{{An elephant at sunset" */>}} {{< /code >}} #### Example `figure` Output -{{< output file="figure-output-example.html" >}} +```html
- -
-

Steve Francia

-
+ +
An elephant at sunset
-{{< /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 -{{}} +```text +{{}} ``` -#### 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" >}} -{{}} -{{< /code >}} +To display a specific file within the gist: -#### Example `gist` Output +```text +{{}} +``` -{{< 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" >}} -{{}} -
-
-

{{ .Title }}

- {{ range .Pages }} - {{ .Render "summary" }} - {{ end }} -
-
+```text +{{}} +{{ range .Pages }} +

{{ .LinkTitle }}

+{{ end }} {{}} -{{< /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 }} +

{{ .LinkTitle }}

+{{ end }} +{{< /highlight >}} -{{< output file="tutorials/learn-html/index.html" >}} -<section id="main"> - <div> - <h1 id="title">{{ .Title }}</h1> - {{ range .Pages }} - {{ .Render "summary"}} - {{ end }} - </div> -</section> -{{< /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 +{{}} +{{ range .Pages }} +

{{ .LinkTitle }}

+{{ end }} +{{}} +``` + +Rendered: + +{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}} +{{ range .Pages }} +

{{ .LinkTitle }}

+{{ 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 {{}} -{{< /code >}} - -You also have the option to hide the caption: - -{{< code file="instagram-input-hide-caption.md" >}} -{{}} -{{< /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 {{}} -{{< /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 +{{}} +``` -{{< code file="example-vimeo-input.md" >}} -{{}} -{{< /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 `
` that wraps the `