Technical documentation sites often need to display code samples.
This section shows you how to do this in your documentation site.
Code blocks display in a monotype font — where each character is the same fixed width —
so that characters in subsequent lines can line up in columns.
Inline code snippet
For a simple code snippet that is less than one line long, simply add a backquote character (`)
to the beginning and end of the code snippet to generate an
inline code block.
Example: The config.yaml file contains the basic configuration data for your Hugo site.
Larger code block
For larger blocks of code, those spanning multiple lines, use a
fenced code block
by adding a line with 3 backquotes before and after the code block.
Here’s an example that displays the code block as simple text:
Fenced code block example markdown
```
// Set up "copy to clipboard" functionality for code blocks, using clipboard.js from https://clipboardjs.com/
if (typeof ClipboardJS !== 'undefined') {
new ClipboardJS('.copy-icon', {
target(trigger) {
return trigger.closest('.jhdocs-code-block').querySelector('.highlight');
},
});
}
```
Here is the rendered result of this markdown:
// Set up "copy to clipboard" functionality for code blocks, using clipboard.js from https://clipboardjs.com/
if (typeof ClipboardJS !== 'undefined') {
new ClipboardJS('.copy-icon', {
target(trigger) {
return trigger.closest('.jhdocs-code-block').querySelector('.highlight');
},
});
}
Using a language specifier
You can add a language specifier after the first set of 3 backquotes to tell the code block how to
display the syntax highlighting appropriate to the language being illustrated.
Here’s that same example, this time with syntax highlighting appropriate for JavaScript:
Fenced Code Block Example
```javascript
// Set up "copy to clipboard" functionality for code blocks, using clipboard.js from https://clipboardjs.com/
if (typeof ClipboardJS !== 'undefined') {
new ClipboardJS('.copy-icon', {
target(trigger) {
return trigger.closest('.jhdocs-code-block').querySelector('.highlight');
},
});
}
```
Here is the rendered result of this markdown:
// Set up "copy to clipboard" functionality for code blocks, using clipboard.js from https://clipboardjs.com/
if(typeofClipboardJS!=='undefined'){newClipboardJS('.copy-icon',{target(trigger){returntrigger.closest('.jhdocs-code-block').querySelector('.highlight');},});}
Code block with copy/paste and expand/collapse functionality
If you really want to help your users, consider making it easier for them to work with your code block by
including a header. The header features buttons that allow the reader to copy the code block from your
documentation so that they can paste it into their code and collapse and expand the code block as
needed for a cleaner reading experience.
To do this, use the jhdocs-code shortcode, wrapping either an inline code snippet or a larger code block.
This shortcode is the ultimate boss for displaying code samples, giving you everything you have in the
other code block approaches, but with an additional header that displays a title, expand/collapse functionality,
and a copy icon that the user can press to copy the code block to the clipboard.
The code snippets use backquotes as described above, but you additionally wrap the entire block in the
jhdocs-code shortcode start/end tags.
This shortcode takes the following parameters:
title: Title to display in the code block header
collapsible: One of “yes” or “no” to specify whether the user can expand and collapse the code block (default is “yes”)
collapsed: One of “yes” or “no” to specify whether the code block is initially collapsed (default is “no”)
The example below is the same multline code block that we saw in earlier examples, wrapped with a jhdocs-code shortcode.
Code block with copy/paste and expand/collapse example markdown
{{< jhdocs-code title="Copy to clipboard functionality" >}}
```javascript
// Set up "copy to clipboard" functionality for code blocks, using clipboard.js from https://clipboardjs.com/
if (typeof ClipboardJS !== 'undefined') {
new ClipboardJS('.copy-icon', {
target(trigger) {
return trigger.closest('.jhdocs-code-block').querySelector('.highlight');
},
});
}
```
{{< /jhdocs-code >}}
Here is the rendered result of this markdown:
Copy to clipboard functionality
// Set up "copy to clipboard" functionality for code blocks, using clipboard.js from https://clipboardjs.com/
if(typeofClipboardJS!=='undefined'){newClipboardJS('.copy-icon',{target(trigger){returntrigger.closest('.jhdocs-code-block').querySelector('.highlight');},});}
Initially collapsed code block
And the same code example, this time with the code block initially collapsed…
Code block with copy/paste and expand/collapse example markdown
{{< jhdocs-code title="Initially collapsed" collapsed="yes" >}}
```javascript
// Set up "copy to clipboard" functionality for code blocks, using clipboard.js from https://clipboardjs.com/
if (typeof ClipboardJS !== 'undefined') {
new ClipboardJS('.copy-icon', {
target(trigger) {
return trigger.closest('.jhdocs-code-block').querySelector('.highlight');
},
});
}
```
{{< /jhdocs-code >}}
Here is the rendered result of this markdown:
Initially collapsed
// Set up "copy to clipboard" functionality for code blocks, using clipboard.js from https://clipboardjs.com/
if(typeofClipboardJS!=='undefined'){newClipboardJS('.copy-icon',{target(trigger){returntrigger.closest('.jhdocs-code-block').querySelector('.highlight');},});}
Code block with line numbers
To display line numbers in your code blocks, add metadata to the right of the code block language specifier
that specifies that you want line numbers in the code block. You can also have the line numbers start at a number
other than 1 if needed.
The metadata for the example below is typescript {linenos=table,linenostart=199}. Place this metadata after the three
initial backticks that open the code block. (We unfortunately can’t show this in the doc here since Hugo interprets
that as an actual code block.)
{{< jhdocs-code title="A code block with line numbers" >}}
```typescript {linenos=table,linenostart=199}
public editForm: FormGroup = new FormGroup({
'name': new FormControl(this.customerInfo.name, Validators.required),
'ssn': new FormControl(this.customerInfo.ssn, Validators.required),
'birthdate': new FormControl(this.customerInfo.birthdate, Validators.required),
'grossIncome': new FormControl(this.customerInfo.grossIncome),
'interestRate': new FormControl(this.customerInfo.interestRate, [Validators.min(3), Validators.max(100)]),
'activeCustomer': new FormControl(this.customerInfo.activeCustomer),
'idChecked': new FormControl(this.customerInfo.idChecked),
'street': new FormControl(this.customerInfo.street, Validators.required),
'city': new FormControl(this.customerInfo.city, Validators.required),
'state': new FormControl(this.customerInfo.state, Validators.required),
'zip': new FormControl(this.customerInfo.zip, [Validators.required, Validators.pattern('^[0-9]{5}(?:[0-9]{4})?$')]),
'country': new FormControl(this.customerInfo.country, Validators.required),
'addressType': new FormControl(this.customerInfo.addressType),
'homePhone': new FormControl(this.customerInfo.homePhone),
'businessPhone': new FormControl(this.customerInfo.businessPhone),
'mobilePhone': new FormControl(this.customerInfo.mobilePhone),
'email': new FormControl(this.customerInfo.email, Validators.email)
}, { validators: CountryAddressTypeValidator });
```
{{< /jhdocs-code >}}
To highlight lines in a code block, add metadata to the right of the code block language specifier
that specifies which line numbers you want to see highlighted in the code block. You can specify individual
line numbers or line number ranges.
The metadata for the example below is typescript {linenos=table,hl_lines=[8,"15-17"],linenostart=199}. Place this
metadata after the three initial backticks that open the code block. (We unfortunately can’t show this in the doc
here since Hugo interprets that as an actual code block.)
Highlighted line numbers are always 1-based, even if your code block line numbers start at a number greater than 1.
In this example, we start the line numbering at line 199, but we still specify 1-based highlighted line numbers,
i.e. we count the first line as line number 1.
Code block with highlighted lines example markdown
{{< jhdocs-code title="A code block with line numbers and highlighted lines" >}}
```typescript {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
public editForm: FormGroup = new FormGroup({
'name': new FormControl(this.customerInfo.name, Validators.required),
'ssn': new FormControl(this.customerInfo.ssn, Validators.required),
'birthdate': new FormControl(this.customerInfo.birthdate, Validators.required),
'grossIncome': new FormControl(this.customerInfo.grossIncome),
'interestRate': new FormControl(this.customerInfo.interestRate, [Validators.min(3), Validators.max(100)]),
'activeCustomer': new FormControl(this.customerInfo.activeCustomer),
'idChecked': new FormControl(this.customerInfo.idChecked),
'street': new FormControl(this.customerInfo.street, Validators.required),
'city': new FormControl(this.customerInfo.city, Validators.required),
'state': new FormControl(this.customerInfo.state, Validators.required),
'zip': new FormControl(this.customerInfo.zip, [Validators.required, Validators.pattern('^[0-9]{5}(?:[0-9]{4})?$')]),
'country': new FormControl(this.customerInfo.country, Validators.required),
'addressType': new FormControl(this.customerInfo.addressType),
'homePhone': new FormControl(this.customerInfo.homePhone),
'businessPhone': new FormControl(this.customerInfo.businessPhone),
'mobilePhone': new FormControl(this.customerInfo.mobilePhone),
'email': new FormControl(this.customerInfo.email, Validators.email)
}, { validators: CountryAddressTypeValidator });
```
{{< /jhdocs-code >}}
Here is the rendered result of this markdown:
A code block with line numbers and highlighted lines