Merge commit '87de22d7464e239c775fbd48ebce1665d5b1e80d'

docs/content/en/templates/shortcode-templates.md

@@ -1,14 +1,14 @@
 ---
-title: Create Your Own Shortcodes
-linktitle: Shortcode Templates
+title: Create your own shortcodes
+linkTitle: Shortcode templates
 description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.
 categories: [templates]
 keywords: [shortcodes,templates]
 menu:
   docs:
     parent: templates
-    weight: 100
-weight: 100
+    weight: 130
+weight: 130
 toc: true
 ---
 
@@ -18,13 +18,13 @@ Shortcodes are a means to consolidate templating into small, reusable snippets t
 Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).)
 {{% /note %}}
 
-## Create Custom Shortcodes
+## Create custom shortcodes
 
 Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs.
 
 {{< youtube Eu4zSaKOY4A >}}
 
-### File Location
+### File location
 
 To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}`.
 
@@ -36,14 +36,14 @@ You can organize your shortcodes in subfolders, e.g. in `layouts/shortcodes/boxe
 
 Note the forward slash.
 
-### Shortcode Template Lookup Order
+### Shortcode template lookup order
 
 Shortcode templates have a simple [lookup order]:
 
 1. `/layouts/shortcodes/<SHORTCODE>.html`
 2. `/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html`
 
-### Positional vs Named Parameters
+### Positional vs. named parameters
 
 You can create shortcodes using the following types of parameters:
 
@@ -57,7 +57,7 @@ For more complex layouts with multiple or optional parameters, named parameters
 
 Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users.
 
-### Access Parameters
+### Access parameters
 
 All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively.
 
@@ -115,7 +115,7 @@ The `.Params` variable in shortcodes contains the list parameters passed to shor
 : these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID)
 
 `$.Page.Params`
-: refers to the page's params; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`).
+: refers to the page's parameters; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`).
 
 `$.Page.Site.Params`
 : refers to global variables as defined in your [site's configuration file][config].
@@ -150,15 +150,15 @@ You can also use the variable `.Page` to access all the normal [page variables][
 
 A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root.
 
-### Checking for Existence
+### Checking for existence
 
 You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
 
-## Custom Shortcode Examples
+## Custom shortcode examples
 
 The following are examples of the different types of shortcodes you can create via shortcode template files in `/layouts/shortcodes`.
 
-### Single-word Example: `year`
+### Single-word example: `year`
 
 Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your Markdown. Your goal is to be able to call the shortcode as follows:
 
@@ -170,7 +170,7 @@ Let's assume you would like to keep mentions of your copyright year current in y
 {{ now.Format "2006" }}
 {{< /code >}}
 
-### Single Positional Example: `youtube`
+### Single positional example: `youtube`
 
 Embedded videos are a common addition to Markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]:
 
@@ -197,7 +197,7 @@ Would load the template at `/layouts/shortcodes/youtube.html`:
 </div>
 {{< /code >}}
 
-### Single Named Example: `image`
+### Single named example: `image`
 
 Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files:
 
@@ -239,7 +239,7 @@ Would be rendered as:
 </figure>
 {{< /code >}}
 
-### Single Flexible Example: `vimeo`
+### Single flexible example: `vimeo`
 
 ```go-html-template
 {{</* vimeo 49718712 */>}}
@@ -271,7 +271,7 @@ Would be rendered as:
 </div>
 {{< /code >}}
 
-### Paired Example: `highlight`
+### Paired example: `highlight`
 
 The following is taken from `highlight`, which is a [built-in shortcode] that ships with Hugo.
 
@@ -298,7 +298,7 @@ The rendered output of the HTML example code block will be as follows:
 </pre></div>
 {{< /code >}}
 
-### Nested Shortcode: Image Gallery
+### Nested shortcode: image gallery
 
 Hugo's [`.Parent` shortcode variable][parent] provides access to the parent shortcode context when the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters.
 
@@ -341,32 +341,32 @@ This will output the following HTML. Note how the first two `img` shortcodes inh
 <img src="/images/three.jpg">
 ```
 
-## Error Handling in Shortcodes
+## Error handling in shortcodes
 
 Use the [errorf](/functions/errorf) template func and [.Position](/variables/shortcodes/) variable to get useful error messages in shortcodes:
 
 ```bash
 {{ with .Get "name" }}
 {{ else }}
-{{ errorf "missing value for param 'name': %s" .Position }}
+{{ errorf "missing value for parameter 'name': %s" .Position }}
 {{ end }}
 ```
 
 When the above fails, you will see an `ERROR` log similar to the below:
 
 ```bash
-ERROR 2018/11/07 10:05:55 missing value for param name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1"
+ERROR 2018/11/07 10:05:55 missing value for parameter name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1"
 ```
 
-## More Shortcode Examples
+## More shortcode examples
 
 More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes].
 
-## Inline Shortcodes
+## Inline shortcodes
 
 You can also implement your shortcodes inline -- e.g. where you use them in the content file. This can be useful for scripting that you only need in one place.
 
-This feature is disabled by default, but can be enabled in your site config:
+This feature is disabled by default, but can be enabled in your site configuration:
 
 {{< code-toggle file="hugo" >}}
 enableInlineShortcodes = true
@@ -386,25 +386,24 @@ The above will print the current date and time.
 
 This means that the current page can be accessed via `.Page.Title` etc. This also means that there are no concept of "nested inline shortcodes".
 
-The same inline shortcode can be reused later in the same content file, with different params if needed, using the self-closing syntax:
+The same inline shortcode can be reused later in the same content file, with different parameters if needed, using the self-closing syntax:
 
  ```go-text-template
 {{</* time.inline /*/>}}
 ```
 
-[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website."
+[basic content files]: /content-management/formats/
 [built-in shortcode]: /content-management/shortcodes/
-[config]: /getting-started/configuration/ "Learn more about Hugo's built-in configuration variables as well as how to us your site's configuration file to include global key-values that can be used throughout your rendered website."
-[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes "Check this section if you are not familiar with the definition of what a shortcode is or if you are unfamiliar with how to use Hugo's built-in shortcodes in your content files."
-[source organization]: /getting-started/directory-structure/#directory-structure-explained "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories."
-[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading."
+[config]: /getting-started/configuration/
+[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
+[source organization]: /getting-started/directory-structure/#directory-structure-explained
+[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes
 [figure]: /content-management/shortcodes/#figure
 [hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes
-[lookup order]: /templates/lookup-order/ "See the order in which Hugo traverses your template files to decide where and how to render your content at build time"
-[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates."
+[lookup order]: /templates/lookup-order/
+[pagevars]: /variables/page/
 [parent]: /variables/shortcodes/
-[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template."
-[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia."
-[templates]: /templates/ "The templates section of the Hugo docs."
+[shortcodesvars]: /variables/shortcodes/
+[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes 
 [vimeoexample]: #single-flexible-example-vimeo
-[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode."
+[youtubeshortcode]: /content-management/shortcodes/#youtube