diff --git a/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md index ad9f5580c..1cb723c62 100644 --- a/content/en/content-management/diagrams.md +++ b/content/en/content-management/diagrams.md @@ -14,7 +14,10 @@ toc: true ## GoAT diagrams (ASCII) -Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block: +Hugo natively supports [GoAT] diagrams with an [embedded code block render hook]. This means that this code block: + +[GoAT]: https://github.com/bep/goat +[embedded code block render hook]: {{% eturl render-codeblock-goat %}} ````txt ```goat diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md index be322ea45..f12fc46b0 100644 --- a/content/en/content-management/shortcodes.md +++ b/content/en/content-management/shortcodes.md @@ -70,13 +70,17 @@ The `<` character indicates that the shortcode's inner content does *not* need f You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps]. -## Use Hugo's built-in shortcodes +## Embedded shortcodes -Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your Markdown content clean. +Use these embedded shortcodes as needed. -### `figure` +### figure -`figure` is an extension of the image syntax in Markdown, which does not provide a shorthand for the more semantic [HTML5 `
` element][figureelement]. +{{% note %}} +To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. + +[source code]: {{% eturl figure %}} +{{% /note %}} The `figure` shortcode can use the following named parameters: @@ -119,13 +123,13 @@ attr attrlink : If the attribution text needs to be hyperlinked, URL of the destination. -#### Example `figure` input +Example usage: -{{< code file=figure-input-example.md >}} +```text {{}} -{{< /code >}} +``` -#### Example `figure` output +Rendered: ```html
@@ -134,7 +138,13 @@ attrlink
``` -### `gist` +### gist + +{{% note %}} +To override Hugo's embedded `gist` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. + +[source code]: {{% eturl gist %}} +{{% /note %}} To display a GitHub [gist] with this URL: @@ -144,7 +154,7 @@ To display a GitHub [gist] with this URL: https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b ``` -Include this in your markdown: +Include this in your Markdown: ```text {{}} @@ -164,7 +174,13 @@ Rendered: {{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}} -### `highlight` +### highlight + +{{% note %}} +To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. + +[source code]: {{% eturl highlight %}} +{{% /note %}} To display a highlighted code sample: @@ -204,8 +220,13 @@ Rendered: {{ end }} {{< /highlight >}} -### `instagram` +### instagram +{{% note %}} +To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. + +[source code]: {{% eturl instagram %}} +{{% /note %}} To display an Instagram post with this URL: @@ -213,7 +234,7 @@ To display an Instagram post with this URL: https://www.instagram.com/p/CxOWiQNP2MO/ ``` -Include this in your markdown: +Include this in your Markdown: ```text {{}} @@ -223,53 +244,100 @@ Rendered: {{< instagram CxOWiQNP2MO >}} -### `param` +### param -Gets a value from the current `Page's` parameters set in front matter, with a fallback to the site parameter value. It will log an `ERROR` if the parameter with the given key could not be found in either. +{{% note %}} +To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. -```sh +[source code]: {{% eturl param %}} +{{% /note %}} + +The `param` shortcode renders a parameter from the page's front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist. + +Example usage: + +```text {{}} ``` -Since `testparam` is a parameter defined in front matter of this page with the value `Hugo Rocks!`, the above will print: +Access nested values by [chaining] the [identifiers]: -{{< param testparam >}} +[chaining]: /getting-started/glossary/#chain +[identifiers]: /getting-started/glossary/#identifier -To access deeply nested parameters, use "dot syntax", e.g: - -```sh -{{}} +```text +{{}} ``` -### `ref` and `relref` - -These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page. - -`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo. +### ref {{% note %}} -Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation. +To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. + +Always use the `{{%/* */%}}` notation when calling this shortcode. + +[source code]: {{% eturl ref %}} {{% /note %}} -`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`. +The `ref` shortcode returns the permalink of the given page reference. -#### Example `ref` and `relref` input +Example usage: -```go-html-template -[Neat]({{}}) -[Who]({{}}) +```text +[Post 1]({{%/* ref "/posts/post-1" */%}}) +[Post 1]({{%/* ref "/posts/post-1.md" */%}}) +[Post 1]({{%/* ref "/posts/post-1#foo" */%}}) +[Post 1]({{%/* ref "/posts/post-1.md#foo" */%}}) ``` -#### Example `ref` and `relref` output - -Assuming that standard Hugo pretty URLs are turned on. +Rendered: ```html -Neat -Who +Post 1 +Post 1 +Post 1 +Post 1 ``` -### `tweet` +### relref + +{{% note %}} +To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. + +Always use the `{{%/* */%}}` notation when calling this shortcode. + +[source code]: {{% eturl relref %}} +{{% /note %}} + +The `relref` shortcode returns the permalink of the given page reference. + +Example usage: + +```text +[Post 1]({{%/* relref "/posts/post-1" */%}}) +[Post 1]({{%/* relref "/posts/post-1.md" */%}}) +[Post 1]({{%/* relref "/posts/post-1#foo" */%}}) +[Post 1]({{%/* relref "/posts/post-1.md#foo" */%}}) +``` + +Rendered: + +```html +Post 1 +Post 1 +Post 1 +Post 1 +``` + +### twitter + +{{% note %}} +To override Hugo's embedded `twitter` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. + +You may call the `twitter` shortcode by using its `tweet` alias. + +[source code]: {{% eturl twitter %}} +{{% /note %}} To display a Twitter post with this URL: @@ -277,17 +345,23 @@ To display a Twitter post with this URL: https://twitter.com/SanDiegoZoo/status/1453110110599868418 ``` -Include this in your markdown: +Include this in your Markdown: ```text -{{}} +{{}} ``` Rendered: -{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}} +{{< twitter user="SanDiegoZoo" id="1453110110599868418" >}} -### `vimeo` +### vimeo + +{{% note %}} +To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory. + +[source code]: {{% eturl vimeo %}} +{{% /note %}} To display a Vimeo video with this URL: @@ -295,7 +369,7 @@ To display a Vimeo video with this URL: https://vimeo.com/channels/staffpicks/55073825 ``` -Include this in your markdown: +Include this in your Markdown: ```text {{}} @@ -306,14 +380,20 @@ Rendered: {{< 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 `