Code
The main text column offers space for 80 characters of code in one line. When we need 120 to fit in one line, we can choose to additionally use the marginal column.
Short snippets of code are usually placed in line with the normal text. Longer pieces of code or entire files should be marked as (fenced) code blocks. Hugo can style and colorize fenced code blocks with the built-in Chroma highlighter.
The theme offers additional layout styles with the attributes {.expand}
and the general positioning attributes.
Syntax
Inline Code
A code snippet is surrounded by single backticks like `code`
.
Code Block
We have two ways to mark a block as code:
- Fenced
- When a block is surrounded by three back-ticks
```
in the line above and beyond it’s a fenced code block. - Indented
- A block of text indented by 4 spaces or a tab is also treated as a code block.
The fenced version of the CommonMark syntax is preferable for two reasons:
The following styling options are only available for fenced blocks:
Code highlighting
Line numbers
Line markers
Line anchors
There is an overlap with the syntax for the extensions footnote and definition-list. When we have subsequent paragraphs there, we need to indent them also by 4 spaces or a tab. If we try to place an indented code block after a footnote reference or a definition detail, Hugo will treat it as this kind of continuation indent and not as a code block.
Highlighting
Chroma can highlight many languages, when we add their usual file suffixes. The Hugo docs include the full list of available languages.
Additional styling for fenced code blocks
In contrast to other block elements the attributes follow the first fence of the code block on the same line after a space, like ```md {linenos=true}
.
The options suitable for Perplex are:
linenos
- Enables or disables line numbers. They are disabled by default for this project — enable them with
linenos=true
. hl_lines
- Especially highlights some code lines. The lines must be given as a set of numbers or ranges enclosed in square brackets. Every range has to be surrounded additionally by quotes:
hl_lines=[2,"5-7"]
. linenostart
- Lets the line numbers begin with a given number, like
linenostart=23
lineanchors
- Adds a prefix to the anchors on the line numbers. With
lineanchors=prefix
for example the anchors are namedprefix-1
,prefix-2
, …
Layout
Inline
The HTML tag to mark the beginning of the code is <code>
. And to mark the end we use the corresponding closing tag </code>
. Markdown text surrounded by backticks like `text`
gets enclosed by these tags. And that’s all about inline code.
Block (default)
The *HTML* tag at the **beginning** of the code is `<code>`.
And to mark the **end** we use the corresponding closing tag `</code>`.
Block with line numbers (table layout)
1The *HTML* tag at the **beginning** of the code is `<code>`.
2And to mark the **end** we use the corresponding closing tag `</code>`.
Long blocks
We can expand the block into the margin:
When all code lines are no longer than 40 characters, we can place them inside or beside the text with the attributes {.left-in}
or {.right}
.
{
"firstName": "John",
"lastName": "Smith",
"age": 35,
"profession": "Last Man Standing"
}
Waltz, nymph, for quick jigs vex Bud! Bright vixens jump; dozy fowl quack. BlewJ’s computer quiz favored proxy hacking.
├── assets
├── config
├── package.json
├── public
├── resources
└── themes
Brick quiz whangs jumpy veldt fox. Jack, love my big wad of sphinx quartz! Sex-charged fop blew my junk TV quiz. Quick brown fox jumps over the lazy dog. Crazy Frederick bought many very exquisite opal jewels.
The last example includes the output of the tree
command in a project directory. Because the folders are all lowercase we can further reduce the line height with the attribute {.lh15}
→ the tree has no gaps.
Indented
The _HTML_ tag at the **beginning** of code is `<code>`.
And to mark the **end** we use the corresponding closing tag `</code>`.