Skip to content

Commit 5f2fd59

Browse files
jmooringjmooring
committed
Elevate embedded shortcode documentation to its own section
Closes gohugoio#2805
1 parent 57cf775 commit 5f2fd59

File tree

20 files changed

+1065
-78
lines changed

20 files changed

+1065
-78
lines changed

‎config/_default/menus/menus.en.toml‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -55,20 +55,26 @@ identifier = 'render-hooks'
5555
pageRef = '/render-hooks/'
5656

5757
[[docs]]
58-
name = 'Hugo Modules'
58+
name = 'Shortcodes'
5959
weight = 100
60+
identifier = 'shortcodes'
61+
pageRef = '/shortcodes/'
62+
63+
[[docs]]
64+
name = 'Hugo Modules'
65+
weight = 110
6066
identifier = 'modules'
6167
pageRef = '/hugo-modules/'
6268

6369
[[docs]]
6470
name = 'Hugo Pipes'
65-
weight = 110
71+
weight = 120
6672
identifier = 'hugo-pipes'
6773
pageRef = '/hugo-pipes/'
6874

6975
[[docs]]
7076
name = 'CLI'
71-
weight = 120
77+
weight = 130
7278
post = 'break'
7379
identifier = 'commands'
7480
pageRef = '/commands/'
@@ -77,25 +83,25 @@ pageRef = '/commands/'
7783

7884
[[docs]]
7985
name = 'Troubleshooting'
80-
weight = 130
86+
weight = 140
8187
identifier = 'troubleshooting'
8288
pageRef = '/troubleshooting/'
8389

8490
[[docs]]
8591
name = 'Developer tools'
86-
weight = 140
92+
weight = 150
8793
identifier = 'developer-tools'
8894
pageRef = '/tools/'
8995

9096
[[docs]]
9197
name = 'Hosting and deployment'
92-
weight = 150
98+
weight = 160
9399
identifier = 'hosting-and-deployment'
94100
pageRef = '/hosting-and-deployment/'
95101

96102
[[docs]]
97103
name = 'Contribute'
98-
weight = 160
104+
weight = 170
99105
post = 'break'
100106
identifier = 'contribute'
101107
pageRef = '/contribute/'

‎content/en/functions/_common/highlighting-options.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
_comment: Do not remove front matter.
3+
---
4+
5+
anchorLineNos
6+
: (`bool`) Whether to render each line number as an HTML anchor element, setting the `id` attribute of the surrounding `span` element to the line number. Irrelevant if `lineNos` is `false`. Default is `false`.
7+
8+
codeFences
9+
: (`bool`) Whether to highlight fenced code blocks. Default is `true`.
10+
11+
guessSyntax
12+
: (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer]. Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`.
13+
14+
[lexer]: /getting-started/glossary/#lexer
15+
16+
{{% note %}}
17+
The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
18+
{{% /note %}}
19+
20+
hl_Lines
21+
: (`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
22+
23+
hl_inline
24+
: (`bool`) Whether to render the highlighted code without a wrapping container. Default is `false`.
25+
26+
lineAnchors
27+
: (`string`) When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `span` element. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
28+
29+
lineNoStart
30+
: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
31+
32+
lineNos
33+
: (`bool`) Whether to display a number at the beginning of each line. Default is `false`.
34+
35+
lineNumbersInTable
36+
: (`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`.
37+
38+
noClasses
39+
: (`bool`) Whether to use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and generate the CSS file using the `hugo gen chromastyles` command. Default is `true`.
40+
41+
style
42+
: (`string`) The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive. Default is `monokai`.
43+
44+
tabWidth
45+
: (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
46+
47+
wrapperClass
48+
{{< new-in 0.140.2 >}}
49+
: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
50+
51+
{{% note %}}
52+
Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
53+
54+
lineNos=inline
55+
: equivalent to `lineNos=true` and `lineNumbersInTable=false`
56+
57+
lineNos=table
58+
: equivalent to `lineNos=true` and `lineNumbersInTable=true`
59+
{{% /note %}}

‎content/en/functions/transform/Highlight.md‎

Lines changed: 16 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -9,81 +9,31 @@ action:
99
- functions/transform/CanHighlight
1010
- functions/transform/HighlightCodeBlock
1111
returnType: template.HTML
12-
signatures: ['transform.Highlight INPUT LANG [OPTIONS]']
12+
signatures: ['transform.Highlight CODE LANG [OPTIONS]']
1313
aliases: [/functions/highlight]
1414
toc: true
1515
---
1616

17-
The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 available styles.
17+
The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [available styles].
18+
19+
[chroma]: https://github.com/alecthomas/chroma
20+
[available styles]: https://xyproto.github.io/splash/docs/
1821

1922
## Arguments
2023

21-
INPUT
22-
: The code to highlight.
24+
The `transform.Highlight` shortcode takes three arguments.
25+
26+
CODE
27+
: (`string`) The code to highlight.
2328

2429
LANG
25-
: The language of the code to highlight. Choose from one of the [supported languages]. Case-insensitive.
30+
: (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
2631

2732
OPTIONS
28-
: A map or comma-separated list of zero or more options. Set default values in [site configuration].
29-
30-
## Options
31-
32-
anchorLineNos
33-
: (`bool`) Whether to render each line number as an HTML anchor element, setting the `id` attribute of the surrounding `span` element to the line number. Irrelevant if `lineNos` is `false`. Default is `false`.
34-
35-
codeFences
36-
: (`bool`) Whether to highlight fenced code blocks. Default is `true`.
37-
38-
guessSyntax
39-
: (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer]. Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`.
40-
41-
[lexer]: /getting-started/glossary/#lexer
42-
43-
{{% note %}}
44-
The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
45-
{{% /note %}}
46-
47-
hl_Lines
48-
: (`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
49-
50-
hl_inline
51-
: (`bool`) Whether to render the highlighted code without a wrapping container.Default is `false`.
52-
53-
lineAnchors
54-
: (`string`) When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `span` element. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
55-
56-
lineNoStart
57-
: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
58-
59-
lineNos
60-
: (`bool`) Whether to display a number at the beginning of each line. Default is `false`.
33+
: (`map or string`) A map or space-separate key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive.
6134

62-
lineNumbersInTable
63-
: (`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`.
64-
65-
noClasses
66-
: (`bool`) Whether to use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and generate the CSS file using the `hugo gen chromastyles` command. Default is `true`.
67-
68-
style
69-
: (`string`) The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive. Default is `monokai`.
70-
71-
tabWidth
72-
: (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
73-
74-
wrapperClass
75-
{{< new-in 0.140.2 >}}
76-
: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
77-
78-
{{% note %}}
79-
Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
80-
81-
lineNos=inline
82-
: equivalent to `lineNos=true` and `lineNumbersInTable=false`
83-
84-
lineNos=table
85-
: equivalent to `lineNos=true` and `lineNumbersInTable=true`
86-
{{% /note %}}
35+
[site configuration]: /getting-started/configuration-markup#highlight
36+
[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages
8737

8838
## Examples
8939

@@ -101,7 +51,6 @@ lineNos=table
10151
{{ transform.Highlight $input $lang $opts }}
10252
```
10353

104-
[Chroma]: https://github.com/alecthomas/chroma
105-
[site configuration]: /getting-started/configuration-markup#highlight
106-
[style gallery]: https://xyproto.github.io/splash/docs/
107-
[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages
54+
## Options
55+
56+
{{% include "functions/_common/highlighting-options" %}}

‎content/en/shortcodes/_index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Shortcodes
3+
linkTitle: In this section
4+
description: Insert elements such as videos, images, and social media embeds into your content using Hugo's embedded shortcodes.
5+
categories: []
6+
keywords: []
7+
menu:
8+
docs:
9+
identifier: shortcodes-in-this-section
10+
parent: shortcodes
11+
weight: 10
12+
weight: 10
13+
showSectionMenu: true
14+
---
15+
16+
Insert elements such as videos, images, and social media embeds into your content using Hugo's embedded shortcodes.

‎content/en/shortcodes/comment.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: Comment
3+
description: Include hidden comments in your content with the comment shortcode.
4+
categories: [shortcodes]
5+
keywords: []
6+
menu:
7+
docs:
8+
identifier: shortcodes-comment
9+
parent: shortcodes
10+
weight:
11+
weight:
12+
---
13+
14+
{{% note %}}
15+
To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
16+
17+
[source code]: {{% eturl comment %}}
18+
{{% /note %}}
19+
20+
{{< new-in "0.137.1" >}}
21+
22+
Use the `comment` shortcode to include comments in your content. Hugo will ignore the text within these comments when rendering your site.
23+
24+
Use it inline:
25+
26+
```text
27+
{{%/* comment */%}} TODO: rewrite the paragraph below. {{%/* /comment */%}}
28+
```
29+
30+
Or as a block comment:
31+
32+
```text
33+
{{%/* comment */%}}
34+
TODO: rewrite the paragraph below.
35+
{{%/* /comment */%}}
36+
```
37+
38+
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‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Details
3+
description: Insert an HTML details element into your content using the details shortcode.
4+
categories: [shortcodes]
5+
keywords: []
6+
menu:
7+
docs:
8+
parent: shortcodes
9+
weight:
10+
weight:
11+
toc: true
12+
---
13+
14+
{{< new-in 0.140.0 >}}
15+
16+
{{% note %}}
17+
To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
18+
19+
[source code]: {{% eturl details %}}
20+
{{% /note %}}
21+
22+
## Example
23+
24+
With this markup:
25+
26+
```text
27+
{{</* details summary="See the details" */>}}
28+
This is a **bold** word.
29+
{{</* /details */>}}
30+
```
31+
32+
Hugo renders this HTML:
33+
34+
```html
35+
<details>
36+
<summary>See the details</summary>
37+
<p>This is a <strong>bold</strong> word.</p>
38+
</details>
39+
```
40+
41+
Which looks like this in your browser:
42+
43+
{{< details summary="See the details" >}}
44+
This is a **bold** word.
45+
{{< /details >}}
46+
47+
## Arguments
48+
49+
summary
50+
: (`string`) The content of the child `summary` element rendered from Markdown to HTML. Default is `Details`.
51+
52+
open
53+
: (`bool`) Whether to initially display the content of the `details` element. Default is `false`.
54+
55+
class
56+
: (`string`) The `class` attribute of the `details` element.
57+
58+
name
59+
: (`string`) The `name` attribute of the `details` element.
60+
61+
title
62+
: (`string`) The `title` attribute of the `details` element.
63+
64+
## Styling
65+
66+
Use CSS to style the `details` element, the `summary` element, and the content itself.
67+
68+
```css
69+
/* target the details element */
70+
details { }
71+
72+
/* target the summary element */
73+
details > summary { }
74+
75+
/* target the children of the summary element */
76+
details > summary > * { }
77+
78+
/* target the content */
79+
details > :not(summary) { }
80+
```

0 commit comments

Comments
 (0)