Elevate embedded shortcode documentation to its own section

Closes gohugoio#2805

Author: jmooring

config/_default/menus/menus.en.toml

@@ -55,20 +55,26 @@ identifier = 'render-hooks'
 pageRef = '/render-hooks/'
 
 [[docs]]
-name = 'Hugo Modules'
+name = 'Shortcodes'
 weight = 100
+identifier = 'shortcodes'
+pageRef = '/shortcodes/'
+
+[[docs]]
+name = 'Hugo Modules'
+weight = 110
 identifier = 'modules'
 pageRef = '/hugo-modules/'
 
 [[docs]]
 name = 'Hugo Pipes'
-weight = 110
+weight = 120
 identifier = 'hugo-pipes'
 pageRef = '/hugo-pipes/'
 
 [[docs]]
 name = 'CLI'
-weight = 120
+weight = 130
 post = 'break'
 identifier = 'commands'
 pageRef = '/commands/'
@@ -77,25 +83,25 @@ pageRef = '/commands/'
 
 [[docs]]
 name = 'Troubleshooting'
-weight = 130
+weight = 140
 identifier = 'troubleshooting'
 pageRef = '/troubleshooting/'
 
 [[docs]]
 name = 'Developer tools'
-weight = 140
+weight = 150
 identifier = 'developer-tools'
 pageRef = '/tools/'
 
 [[docs]]
 name = 'Hosting and deployment'
-weight = 150
+weight = 160
 identifier = 'hosting-and-deployment'
 pageRef = '/hosting-and-deployment/'
 
 [[docs]]
 name = 'Contribute'
-weight = 160
+weight = 170
 post = 'break'
 identifier = 'contribute'
 pageRef = '/contribute/'

content/en/shortcodes/_index.md

@@ -0,0 +1,16 @@
+---
+title: Shortcodes
+linkTitle: In this section
+description: Insert elements such as videos, images, and social media embeds into your content using Hugo's embedded shortcodes.
+categories: []
+keywords: []
+menu:
+  docs:
+    identifier: shortcodes-in-this-section
+    parent: shortcodes
+    weight: 10
+weight: 10
+showSectionMenu: true
+---
+
+Insert elements such as videos, images, and social media embeds into your content using Hugo's embedded shortcodes.

content/en/shortcodes/comment.md

@@ -0,0 +1,38 @@
+---
+title: Comment
+description: Include hidden comments in your content with the comment shortcode.
+categories: [shortcodes]
+keywords: []
+menu:
+  docs:
+    identifier: shortcodes-comment
+    parent: shortcodes
+    weight:
+weight:
+---
+
+{{< new-in "0.137.1" >}}
+
+{{% note %}}
+To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
+
+[source code]: {{% eturl comment %}}
+{{% /note %}}
+
+Use the `comment` shortcode to include comments in your content. Hugo will ignore the text within these comments when rendering your site.
+
+Use it inline:
+
+```text
+{{%/* comment */%}} TODO: rewrite the paragraph below. {{%/* /comment */%}}
+```
+
+Or as a block comment:
+
+```text
+{{%/* comment */%}}
+TODO: rewrite the paragraph below.
+{{%/* /comment */%}}
+```
+
+Although you can call this shortcode using the `{{</* */>}}` notation, computationally it is more efficient to call it using the `{{%/* */%}}` notation as shown above.

content/en/shortcodes/details.md

@@ -0,0 +1,80 @@
+---
+title: Details
+description: Insert an HTML details element into your content using the details shortcode.
+categories: [shortcodes]
+keywords: []
+menu:
+  docs:
+    parent: shortcodes
+    weight:
+weight:
+toc: true
+---
+
+{{< new-in 0.140.0 >}}
+
+{{% note %}}
+To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
+
+[source code]: {{% eturl details %}}
+{{% /note %}}
+
+## Example
+
+With this markup:
+
+```text
+{{</* details summary="See the details" */>}}
+This is a **bold** word.
+{{</* /details */>}}
+```
+
+Hugo renders this HTML:
+
+```html
+<details>
+  <summary>See the details</summary>
+  <p>This is a <strong>bold</strong> word.</p>
+</details>
+```
+
+Which looks like this in your browser:
+
+{{< details summary="See the details" >}}
+This is a **bold** word.
+{{< /details >}}
+
+## Arguments
+
+summary
+: (`string`) The content of the child `summary` element rendered from Markdown to HTML. Default is `Details`.
+
+open
+: (`bool`) Whether to initially display the content of the `details` element. Default is `false`.
+
+class
+: (`string`) The `class` attribute of the `details` element.
+
+name
+: (`string`) The `name` attribute of the `details` element.
+
+title
+: (`string`) The `title` attribute of the `details` element.
+
+## Styling
+
+Use CSS to style the `details` element, the `summary` element, and the content itself.
+
+```css
+/* target the details element */
+details { }
+
+/* target the summary element */
+details > summary { }
+
+/* target the children of the summary element */
+details > summary > * { }
+
+/* target the content */
+details > :not(summary) { }
+```

content/en/shortcodes/figure.md

@@ -0,0 +1,122 @@
+---
+title: Figure
+description: Insert an HTML figure element into your content using the figure shortcode.
+categories: [shortcodes]
+keywords: []
+menu:
+  docs:
+    parent: shortcodes
+    weight:
+weight:
+toc: true
+---
+
+{{% 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 %}}
+
+## Example
+
+With this markup:
+
+```text
+{{</* figure
+  src="/images/examples/zion-national-park.jpg"
+  alt="A photograph of Zion National Park"
+  link="https://www.nps.gov/zion/index.htm"
+  caption="Zion National Park"
+  class="ma0 w-75"
+*/>}}
+```
+
+Hugo renders this HTML:
+
+```html
+<figure class="ma0 w-75">
+  <a href="https://www.nps.gov/zion/index.htm">
+    <img 
+      src="/images/examples/zion-national-park.jpg" 
+      alt="A photograph of Zion National Park"
+    >
+  </a>
+  <figcaption>
+    <p>Zion National Park</p>
+  </figcaption>
+</figure>
+```
+
+Which looks like this in your browser:
+
+{{< figure
+  src="/images/examples/zion-national-park.jpg"
+  alt="A photograph of Zion National Park"
+  link="https://www.nps.gov/zion/index.htm"
+  caption="Zion National Park"
+  class="ma0 w-75"
+>}}
+
+## Arguments
+
+{{< comment >}}
+TODO The last thing to do is reword all of these.
+{{< /comment >}}
+
+src
+: (`string`) URL of the image to be displayed.
+
+class
+: (`string`) The `class` attribute of the `figure` element.
+
+alt
+: (`string`) Alternate text for the image if the image cannot be displayed.
+
+loading
+: (`string`) The `loading` attribute of the `img` element.
+
+height
+: (`int`) The `height` attribute of the `img` element.
+
+width
+: (`int`) The `width` attribute of the `img` element.
+
+title
+: (`string`) Image title.
+
+caption
+: (`string`) Image caption. Markdown within the value of `caption` will be rendered.
+
+link
+: (`string`) If the image needs to be hyperlinked, URL of the destination.
+
+target
+: (`string`) Applicable if the `link` argument is set, the `target` attribule of the anchor element. 
+
+rel
+: (`string`) Optional `rel` attribute for the URL if `link` argument is set.
+
+attr
+: (`string`) Image attribution text. Markdown within the value of `attr` will be rendered.
+
+attrlink
+: (`string`) If the attribution text needs to be hyperlinked, URL of the destination.
+
+## Image location
+
+The `figure` shortcode resolves internal Markdown destinations by looking for a matching [page resource], falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
+
+[page resource]: /getting-started/glossary/#page-resource
+[global resource]: /getting-started/glossary/#global-resource
+
+You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}

content/en/shortcodes/gist.md

@@ -0,0 +1,13 @@
+---
+title: Gist
+description: Embed a GitHub Gist in your content using the gist shortcode.
+categories: [shortcodes]
+keywords: []
+menu:
+  docs:
+    parent: shortcodes
+    weight:
+weight:
+---
+
+TODO

content/en/shortcodes/highlight.md

@@ -0,0 +1,21 @@
+---
+title: Highlight
+description: Insert syntax-highlighted code into your content using the highlight shortcode.
+categories: [shortcodes]
+keywords: []
+menu:
+  docs:
+    parent: shortcodes
+    weight:
+weight:
+---
+
+TODO
+
+{{% note %}}
+With the Markdown [content format], the `highlight` shortcode is rarely needed because, by default, Hugo automatically applies syntax highlighting to fenced code blocks.
+
+The primary use case for the `highlight` shortcode in Markdown is to apply syntax highlighting to inline code snippets.
+
+[content format]: /content-management/formats/
+{{% /note %}}

content/en/shortcodes/instagram.md

@@ -0,0 +1,13 @@
+---
+title: Instagram
+description: Embed an Instagram post in your content using the instagram shortcode.
+categories: [shortcodes]
+keywords: []
+menu:
+  docs:
+    parent: shortcodes
+    weight:
+weight:
+---
+
+TODO

content/en/shortcodes/param.md

@@ -0,0 +1,13 @@
+---
+title: Param
+description: Insert a front matter field into your content using the param shortcode.
+categories: [shortcodes]
+keywords: []
+menu:
+  docs:
+    parent: shortcodes
+    weight:
+weight:
+---
+
+TODO