Code blocks are operational UX, not decoration

I used to treat code block styling as visual polish.

Today I don’t.

During incident work, code blocks are command surfaces. If they are ambiguous, they create execution risk.

The difference between “this is executable shell” and “this is generic code” is small in markup and large in operator behavior.

What changed

I added two behaviors to my Hugo sites:

1. Copy button on fenced blocks (div.highlight > pre)
2. Visual $ prompt hint for shell-language fences (bash/sh/zsh/shell)

The prompt is visual only. Copy still produces clean commands without PS1 artifacts.

That matters because readers have different shells and aliases. A copied command should execute as-is.

Why this is operational, not cosmetic

In platform incidents, I’m often moving fast between logs, docs, and terminals.

When command blocks look like narrative text, or copy behavior includes extra prompt characters, I either slow down to sanitize commands manually or accept avoidable failure modes.

Both are expensive.

A clear shell affordance plus clean copy path reduces friction at the exact moment where cognitive load is highest.

Implementation pattern (Hugo)

• Inject small CSS/JS via layouts/partials/custom_head.html and custom_body.html.
• Detect shell fences by language class (language-bash, data-lang="bash", etc.).
• Add a cli-block class for shell-only visual treatment.
• Keep inline code untouched.

I also had to tune spacing carefully. The first pass looked fine in theory and wrong in the browser: code started lower than expected because inherited block styles interacted with the button placement.

The fix was to scope overrides narrowly and verify against real rendered markup, not assumptions.

Principle

If your audience executes commands from your docs, code-block UX is part of reliability engineering.

Not branding. Not aesthetics. Reliability.