Create links to referenced embedded templates

Closes #2370

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

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 `<figure>` 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
 {{</* figure src="elephant.jpg" title="An elephant at sunset" */>}}
-{{< /code >}}
+```
 
-#### Example `figure` output
+Rendered:
 
 ```html
 <figure>
@@ -134,7 +138,13 @@ attrlink
 </figure>
 ```
 
-### `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
 {{</* gist user 50a7482715eac222e230d1e64dd9a89b */>}}
@@ -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,16 +220,21 @@ 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:
 
 ```text
 https://www.instagram.com/p/CxOWiQNP2MO/
 ```
 
-Include this in your markdown:
+Include this in your Markdown:
 
 ```text
 {{</* instagram CxOWiQNP2MO */>}}
@@ -223,79 +244,132 @@ Rendered:
 
 {{< instagram CxOWiQNP2MO >}}
 
-### `param`
+### param
+
+{{% note %}}
+To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
+
+[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.
 
-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.
+Example usage:
 
-```sh
+```text
 {{</* param testparam */>}}
 ```
 
-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:
+```text
+{{</* param my.nested.param */>}}
+```
+
+### ref
+
+{{% note %}}
+To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
 
-```sh
-{{</* param "my.nested.param" */>}}
+Always use the `{{%/* */%}}` notation when calling this shortcode.
+
+[source code]: {{% eturl ref %}}
+{{% /note %}}
+
+The `ref` shortcode returns the permalink of the given page reference.
+
+Example usage:
+
+```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" */%}})
 ```
 
-### `ref` and `relref`
+Rendered:
 
-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.
+```html
+<a href="http://example.org/posts/post-1/">Post 1</a>
+<a href="http://example.org/posts/post-1/">Post 1</a>
+<a href="http://example.org/posts/post-1/#foo">Post 1</a>
+<a href="http://example.org/posts/post-1/#foo">Post 1</a>
+```
 
-`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo.
+### relref
 
 {{% note %}}
-Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation.
+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 %}}
 
-`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`.
+The `relref` shortcode returns the permalink of the given page reference.
 
-#### Example `ref` and `relref` input
+Example usage:
 
-```go-html-template
-[Neat]({{</* ref "blog/neat.md" */>}})
-[Who]({{</* relref "about.md#who" */>}})
+```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" */%}})
 ```
 
-#### Example `ref` and `relref` output
-
-Assuming that standard Hugo pretty URLs are turned on.
+Rendered:
 
 ```html
-<a href="https://example.org/blog/neat">Neat</a>
-<a href="/about/#who">Who</a>
+<a href="/posts/post-1/">Post 1</a>
+<a href="/posts/post-1/">Post 1</a>
+<a href="/posts/post-1/#foo">Post 1</a>
+<a href="/posts/post-1/#foo">Post 1</a>
 ```
 
-### `tweet`
+### 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:
 
 ```txt
 https://twitter.com/SanDiegoZoo/status/1453110110599868418
 ```
 
-Include this in your markdown:
+Include this in your Markdown:
 
 ```text
-{{</* tweet user="SanDiegoZoo" id="1453110110599868418" */>}}
+{{</* twitter user="SanDiegoZoo" id="1453110110599868418" */>}}
 ```
 
 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:
 
 ```text
 https://vimeo.com/channels/staffpicks/55073825
 ```
 
-Include this in your markdown:
+Include this in your Markdown:
 
 ```text
 {{</* vimeo 55073825 */>}}
@@ -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 `<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`.
+If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` 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`.
 
 ```go
 {{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
 ```
 {{% /note %}}
 
-### `youtube`
+### youtube
+
+{{% 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 %}}
 
 The `youtube` shortcode embeds a responsive video player for [YouTube videos]. Only the ID of the video is required, e.g.:
 

content/en/content-management/urls.md

@@ -423,10 +423,12 @@ Hugo renders alias files before rendering pages. A new page with the previous fi
 
 ### Customize
 
-Create a new template (`layouts/alias.html`) to customize the content of the alias files. The template receives the following context:
+To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the layouts directory. The template receives the following context:
 
 Permalink
 : the link to the page being aliased
 
 Page
 : the Page data for the page being aliased
+
+[source code]: {{% eturl alias %}}