Code Blocks
A code block uses an ordinary Markdown fence. Hugo’s embedded Chroma highlighter runs at build time. The browser has no highlighter.
Use code blocks for commands, configuration snippets, and source code.
The {…} attributes on the fence’s info line control the title bar, copy behavior, line numbers, and line anchors.
Diagram fences such as mermaid, echarts, and filetree use their own render hooks.
Optional presentation
A one-line fence with {class="td-code-command"} becomes a compact command strip with a separate copy column. OINK 1.4.0 supports this variant; see examples and fallback rules. Multiline, numbered, or collapsed blocks warn and retain regular presentation.
Shortest form
A fence without attributes still has the complete shell and a copy button. Without a title, there is no empty title bar.
The copy button appears at the top right on hover or when focus enters the block. It is always visible on touch devices.
The shell does not display the language. It stores the lexer name in data-language for stylesheets and tests.
The language tag is Chroma’s lexer name. A diff fence displays a patch with Chroma’s styles for added and removed lines.
It needs no additional component:
Filename titles
title adds a visible title bar, usually containing a filename or path. It also sets the block’s accessible name.
filename is a historical alias for title. If you provide both, the theme warns and uses filename.
Line numbers, start line and highlighting
lineNos accepts inline or table. Inline numbers share the code column.
Table numbers have a separate column, can be selected separately, and are never copied.
lineNoStart sets the first displayed number. hl_lines marks source lines for emphasis.
It counts from 1 inside the fence, independently of lineNoStart.
lineNos="table" puts numbers in a separate column. The copy button removes line numbers in both modes:
tabWidth sets the number of spaces per tab. The theme passes it and style directly to Chroma.
This site uses class-based Chroma palettes for light and dark modes.
Here, style takes effect only if Hugo is changed to inline style mode.
Wrapping long lines
wrap=true changes only the display. It preserves the source and copied text. Without it, long lines scroll horizontally.
wrap=true cannot be combined with table line numbers. Wrapping misaligns the separate number and code cells.
If you provide both, the theme warns and disables wrapping. It suggests lineNos="inline" or removing wrapping.
Folding long code
collapse=N initially shows N lines, with a “show all N lines” button below them.
The server emits complete code. After measuring line N, the browser clips the visual display.
The complete code remains available without JavaScript, in screen readers, and in print.
If the block is no longer than collapse, no button appears. Wrapping and folding can be combined.
Folding measures the bottom of the Nth source-line node, so it never cuts a wrapped line in half.
What gets copied
By default, the copy button copies the complete source. For console and shell-session lexers, it copies only commands.
It keeps prompted lines but removes prompts and output lines. The example below copies two commands, without $ or output.
To include prompts and output, use copy="all".
On ordinary lexers such as bash or sh, copy="command" warns and uses copy="all", because those lexers cannot distinguish prompts, commands, and output.
For multiline commands, put a continuation prompt, usually >, on each continuation line. Otherwise, those lines are treated as output and excluded.
If a session-lexer block has no prompt, copying fails. The icon shows an error, and an error is logged to the console. The clipboard stays unchanged. The button never falls back to copying everything.
copy=false removes a block’s copy button. Use it for counter-examples that readers should not paste:
To disable copying by default, use params.ui.code_copy: false. An explicit copy fence attribute overrides the default.
See Configuration.
The copy button uses only an icon. Success or failure changes the icon and announces a localized status.
Copied text keeps indentation, blank lines, and Unicode. It removes line numbers and ends with exactly one newline.
Line links and stable IDs
To link “see line 3”, give the fence an explicit id, then enable anchorLineNos=true.
Line numbers become links of the form #<id>-<line>.
Jump to line 4.
Without an id, the theme generates an ID that is unique on the page. It depends on the fence’s position.
Adding another fence above it changes the ID. Only an author-provided id is a permanent link.
IDs must contain no whitespace or control characters. They must not duplicate viewport, tab, panel, title, or line-anchor IDs on the page.
Invalid or duplicate IDs warn and use a generated fallback.
Numbered examples
For books or long manuals, use num and caption to create a numbered Book “example” target.
xref can reference the target, which also appears in the book-wide list of examples.
The author provides the number. The theme never counts examples. id defaults to eg-<num>.
See Example 4-1.
num and caption must appear together. A caption without a number is ignored. A number without a caption is removed with a warning.
num cannot be combined with the tab attribute tab.
For figure, table, and equation numbering and indexing, see publishing books.
A set of fences as tabs
The browser combines consecutive fences with tab into a tab set.
Add group to the first fence to enable shared links, synchronization, and saved selections.
See Tabs for group syntax, URL hashes, synchronization across groups, and tabs in prose.
Common errors
- Showing a shortcode in the docs: a fence does not stop Hugo from parsing, so a
{{< tabs >}}written inside a code block still executes. To display it verbatim, add a comment marker inside each delimiter —{{</* tabs */>}}, and{{%/* steps */%}}for the percent form. Every shortcode shown on this page is written that way. - Fences inside fences: four backticks outside, three inside — every “Source” block on this page does it. Add another backtick when the inner block has fences of its own.
- Attributes go on the info line: a fence’s attributes follow the language on the opening line. Only tables and images take their attributes on the line below. Put them on the next line and you get a visible line of braces.
- Unknown, unsafe, and theme-reserved attributes warn and are ignored; the message lists the allowed names.
- Fences in list items: indent them to line up with the item’s content (three
spaces after
1.), or the fence leaves the list.
Output
| Output | Shape |
|---|---|
| HTML | A <div class="td-code"> shell around Chroma’s .highlight/.chroma; copy and fold buttons ship hidden and appear once the script confirms it can run |
| Complete code; copy, fold and the fade are removed; long blocks may break across pages; the title bar stays | |
| Markdown | The source fence, {…} attributes and all, emitted as written |
| RSS | A static code block with no buttons |
A page with no copy or fold control never loads code-block.js; print, Markdown
and RSS never load it.
Parameter reference
Inside the {…} after the language on the opening line, OINK’s own attributes:
tab, ,- Tab label, see Tabs; mutually exclusive with
num
title, filename, and label give the block an accessible name and role="group".
If you also provide aria-label, aria-labelledby, or role, the theme warns and ignores the conflicting attribute.
These three attributes pass through only if the block has neither a title nor label.
The same line accepts Chroma options. The theme passes them to Hugo unchanged:
Limits
- The highlighter cannot be replaced. There is no Shiki, Twoslash, browser highlighting, or runnable playground.
For patches, use a
difffence. Chroma’s.gi/.gdstyle added and removed lines. copy="command"supports only session lexers. Other languages warn and copy everything.- Generated IDs are not permanent links. Write
idfor a link that you plan to share. mermaid,math,chem,markmap,plantuml,echarts,infographic,checksums,filetree, andgalleryare not code blocks. Each has its own render hook, without a code shell or copy button.
Related
- Tabs — the full rules for assembling adjacent fences
- Include — pull a real file from the repository in as a code block
- Publishing books — numbered examples, cross references, the list of examples
- Print — what long code looks like on paper