Code block

2026.08.18 Content

The code block is the dark viewer around every fenced code example: a Monokai-styled panel with Chroma syntax highlighting and a copy button in the top-right corner. Authors write a plain fenced block; the render hook adds the frame, the highlighting, and the button.

Every fenced code block on the site is the live component — the example below renders inside the dark viewer, copy button included:

markup:
  highlight:
    codeFences: true
    noClasses: true
    style: monokai

When to use#

Fenced code blocks only: every fence in Markdown content gets the viewer automatically, and pages never add the wrapper by hand
Multi-line code, commands, and configuration that a reader may want to copy verbatim; single identifiers stay inline code spans
Not for diagrams — a mermaid fence bypasses the viewer entirely and renders through the Mermaid path instead
Keep the content read-only: a code block is something to read and copy, never a place for links or controls

Implementation#

```yaml
markup:
  highlight:
    style: monokai
```

<div class="code-block not-prose">
  <button class="copy-btn-inline code-block-copy" type="button" aria-label="Copy" title="Copy" data-copy-label="Copy" data-copied-label="Copied">
    <svg class="code-block-copy-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">…</svg>
    <span class="sr-only" aria-live="polite">Copy</span>
  </button>
  <div class="code-block-body" tabindex="0" role="region" aria-label="Scrollable code">
    <pre><code>…highlighted code…</code></pre>
  </div>
</div>

The render hook is layouts/_default/_markup/render-codeblock.html: it wraps every non-Mermaid fence in .code-block, adds the copy button with its i18n labels, and highlights the code with transform.Highlight. Highlighting follows the site’s markup.highlight configuration — style: monokai with noClasses: true, so Chroma emits inline styles and no highlight stylesheet exists. The .code-block rules in assets/css/site.css pin the #272822 background and make .code-block-body the horizontal scroll region; that region carries tabindex="0" and role="region" with the codeBlockScrollRegion i18n label, so keyboard users can reach and scroll it even when the code contains no focusable content. Copying is the document-level click listener in assets/js/site.js bound to .copy-btn-inline: it copies the block’s text through the shared copyText helper — the same clipboard fallback path the Copy as Markdown button uses — strips the trailing newline, and swaps the hidden label to Copied for 1.4 seconds.

Options#

Option	Purpose
Language identifier	Picks the Chroma lexer, as in ```yaml; plain text when omitted
`mermaid`	Diverts the fence to the Mermaid diagram path — no dark viewer, no copy button
Fence attributes	Passed to `transform.Highlight` as options, so Chroma settings such as `{hl_lines="2"}` apply

Interface manifest

Kind: Component
Category: Content
Status: Implemented
Implementation: Layout:layouts/_default/_markup/render-codeblock.htmlCSS:assets/css/site.cssJavaScript:assets/js/site.jsi18n:copyCodecopiedCodecodeBlockScrollRegion

Accessibility#

The copy control is a native <button type="button">, so click, Enter, and Space all activate it; it carries its name as aria-label, a matching title, and a visually hidden sr-only span, while the icon is aria-hidden="true"
The sr-only span carries aria-live="polite", so the swap to Copied is announced by screen readers instead of shown only visually
The copy button and the scroll region are the block’s only tab stops — .code-block-body carries tabindex="0" and role="region" so keyboard users can reach and scroll wide code even when it contains no focusable content
Avoid placing links or other interactive elements inside code content — the viewer’s contract is read-only text with one copy action