GitHub-Style Code Blocks: Title Bars, Copy Buttons, Line Numbers, and Highlighted Lines

What “good” looks like in production docs

GitHub-style code blocks aren’t about looking pretty. They’re about reducing operational risk. When someone is following a runbook at 03:00, the code block is the interface. If it lies, confuses, or copies the wrong bytes, your “docs site” just became an outage contributor.

So here’s the bar I use:

• Copy is exact. It copies only the code. Not prompts, not line numbers, not invisible Unicode confetti.
• Line numbers are purely presentational. They help refer to “line 17” without contaminating clipboard content.
• Highlighted lines are data-driven. The author can specify which lines matter (diff context, “change this”, “do not run”).
• Title bar carries useful metadata. Filename, language, maybe “shell”, maybe “k8s”, maybe “output”. Not meaningless decoration.
• Accessible by default. Copy button works with keyboard, announces status, and doesn’t steal focus like a toddler with a new drum kit.
• Fast. Rendering 30 code blocks shouldn’t turn a doc page into a space heater.
• Works offline and under CSP. Production systems tend to have policies. Your docs should survive them.

And yes, I’m going to treat a “code block widget” like a mini production system. Because it is. It’s a distributed system too: author, renderer, browser, clipboard API, and the user’s patience—none of which you fully control.

Facts and short history (why GitHub won)

Some context helps you make better choices. These are small facts, but they explain why the ecosystem looks the way it does.

1. Early web code samples were plain <pre>. “Syntax highlighting” started as server-side regex hacks in the 1990s, long before browsers had good fonts or layout engines.
2. Pygments (mid-2000s) made highlighting mainstream. It popularized the “tokenize and style spans” model that most highlighters still use.
3. GitHub popularized fenced code blocks in Markdown. The triple-backtick convention became the default mental model for code in docs.
4. Clipboard APIs evolved late. For years, “copy” meant selecting text and hoping the DOM didn’t include garbage; modern Clipboard API made reliable copy buttons possible.
5. Line numbers have always been controversial. IDEs need them; docs often shouldn’t. The debate exists because line numbers are useful but easy to implement incorrectly.
6. Client-side highlighting was a reaction to static hosting. When everyone started deploying docs to CDNs, shipping JS highlighters felt simpler than server-side rendering—until performance bills arrived.
7. GitHub’s own UI patterns became a de facto standard. The title bar + copy button is familiar, so users trust it and use it without thinking.
8. Highlighters now compete on “semantic” correctness. Tree-sitter and similar parsers raised the bar; regex tokenizers are faster to build, but less accurate for complex languages.

Two takeaways: first, most “code block” features are bolted onto old primitives. Second, what looks like a simple UI is usually three separate systems duct-taped together: rendering, interaction, and authoring.

Architecture: one component, three data paths

A GitHub-like code block component has three paths that must agree:

If these diverge, you get failure modes that look like user error but aren’t:

• Copy button copies prompts or numbers → pasted command fails → user mistrusts docs.
• Highlighted lines don’t match the actual code due to wrapped lines or hidden spans → user changes the wrong thing.
• Line numbers shift between SSR and hydration → people comment “line 14” and mean different content.

Choose your rendering strategy: SSR, build-time, or client-side

You get three realistic options:

I’m opinionated here: for most documentation and operational runbooks, do highlighting at build time or SSR. Client-side highlighting is a tax you pay forever.

Define an explicit code block model

Stop letting Markdown parsing “decide” what your code block is. Model it. At minimum:

• language (bash, yaml, json, …)
• title (filename, or label like “nginx.conf”)
• code (raw content, normalized line endings)
• highlight (line ranges: 3,5-8)
• showLineNumbers (bool)
• copyTextOverride (optional; e.g., strip prompts)
• kind (source, terminal, output, diff)

Once you have that model, your renderer can be deterministic, testable, and boring. Boring is good. Boring ships.

Copy button: correctness before cleverness

A copy button that occasionally copies the wrong thing is worse than no copy button. It creates confidence, and then betrays it.

What to copy (and what not to)

Rules that work in real environments:

• Never copy line numbers. They are UI chrome. Keep them out of the text node being copied.
• Never copy prompts by default. Prompts are useful visually (“this is a command”), but they are poison when pasted into a non-interactive shell.
• Normalize line endings to \n on copy. Clipboard content should be consistent across OSes; the terminal will cope.
• Trim exactly one trailing newline (optional). GitHub typically copies without adding weird whitespace; match that expectation.
• Do not rewrite tabs to spaces. People copy Makefiles, YAML, and Python. Don’t be “helpful.”

Joke #1: Copy buttons are like backups—everyone assumes they work right up until the day they don’t.

Clipboard API and fallbacks

Modern browsers support navigator.clipboard.writeText(), but you need to plan for:

• Permission constraints (some contexts restrict clipboard access).
• HTTP vs HTTPS (clipboard API generally wants secure contexts).
• Content Security Policy (inline scripts and event handlers might be blocked).

Implementation guidance:

• Prefer a button element with type="button".
• Set aria-label="Copy code".
• Use aria-live region for “Copied” feedback, not alert popups.
• Copy from a stored string (your model’s copyTextOverride or raw code), not from innerText of the displayed DOM, which can include line numbers and hidden spans.

Prompts: display them, don’t copy them

People love prompt-style snippets because they communicate context quickly. But prompts also break copy/paste. The sane compromise is:

• Render prompts visually (e.g., with a separate span).
• Store a prompt-free copy payload.
• Offer an optional “copy with prompts” toggle for training docs, if you must.

Line numbers: UX candy with sharp edges

Line numbers improve collaboration: “change line 42” is a clean instruction. But they come with traps.

How line numbers go wrong

• They get copied. If you implement them by inserting actual text nodes at line starts, they’ll leak into selection and clipboard.
• They drift. If wrapping changes what users perceive as “a line,” they’ll refer to the wrong thing.
• They break search. Some implementations alter the DOM so browser find-in-page stops matching expected code segments cleanly.
• They slow rendering. Splitting into thousands of line elements can turn into a DOM explosion.

Implementation patterns that survive load

Two patterns tend to work:

1. CSS counters for line numbers, without inserting numbers into text. This is fast, and selection can be kept clean.
2. Separate gutter column with line numbers as their own elements, while the code text remains a separate selectable block.

If you highlight lines by wrapping each line in an element, you’re already splitting lines. That’s fine for small blocks, but you need a cutoff. Past a certain size, switch to “no line-level DOM.”

Highlighted lines: the fastest way to reduce mistakes

Highlighting lines is not decoration. It’s a guardrail. Used correctly, it cuts the cognitive load of “which part do I change?”

Good uses

• Call out edits in config files: show the full file, highlight only the lines that differ.
• Point to dangerous commands: highlight the destructive line in a multi-step snippet.
• Diff-style teaching: highlight lines that correspond to a change request from a peer review.

Bad uses

• Highlighting half the block. That’s not emphasis; that’s a highlighter tantrum.
• Using highlight color with low contrast in dark mode. People will miss it.
• Highlighting based on “wrapped visual lines.” It’s a nightmare. Use logical lines only.

Authoring format: keep it boring

Don’t invent a new mini-language for line ranges. Use the established “1,3-5,8” format. Parse it deterministically and fail loudly.

If the author requests highlight lines outside the block length, you have two sane choices:

• Fail the build (my preference for runbooks), or
• Warn and ignore (acceptable for blogs).

Title bars: filenames, language chips, and metadata

A title bar is useful when it provides orientation. “Here’s /etc/nginx/nginx.conf” is actionable. “Code” is not.

What to include

• Filename or label (e.g., values.yaml, docker-compose.yml).
• Language (a small chip helps: bash, yaml, json).
• Copy button with clear affordance.
• Optional “view raw” for very large blocks (serve as a file, not a 10k-line DOM).

Don’t overload it

Title bars are not dashboards. If you cram commit hashes, timestamps, and environment names into it, you’ve built an accordion of distractions. Keep it minimal, consistent, and stable across the site.

Performance and operational concerns (yes, really)

Code blocks become a performance problem in three predictable scenarios:

• Many blocks on one page (runbooks tend to be dense).
• Huge blocks (generated configs, logs, Kubernetes manifests).
• Client-side highlighting (CPU spikes, long tasks, jank).

What to budget

Think in budgets like you would for an API:

• CPU: avoid tokenizing large content on the client.
• DOM nodes: avoid per-line wrappers above a threshold.
• JS bytes: don’t ship 40 languages if you need 6.
• Fonts: a monospaced font fallback is fine; don’t block rendering on fancy fonts.

Caching matters (even for highlighting)

If you do server-side or build-time highlighting, cache the output by a stable key: hash(code + language + theme + highlighter-version). Otherwise you’ll re-highlight the same snippets for every build or request, and your CI will start to feel like it’s mining cryptocurrency.

Security: treat code blocks as untrusted text

If your system renders user-generated code, assume the content is hostile. Syntax highlighting often injects HTML spans; if you don’t sanitize correctly, you can create XSS through “code.”

The safest approach is to render tokens into HTML with escaping done centrally, and never allow raw HTML passthrough inside code blocks.

Instrumentation and monitoring for code blocks

If you ship a copy button and never measure it, you’ll learn about failures via angry humans. Instrument it.

What to measure

• Copy success rate (promise resolved vs rejected).
• Time to interactive on pages with many code blocks.
• Long tasks after page load (client-side highlighting is a repeat offender).
• DOM node count on large pages (a proxy for “we wrapped every line”).
• Build-time highlighting duration (if it spikes, you changed something).

Logging without being creepy

Do not log the code content on copy events. You’ll end up with secrets, tokens, and API keys in analytics. Log only metadata: page id, language, block length, whether prompts were present, success/failure.

Joke #2: The only thing more sensitive than production secrets is the legal team’s reaction when you log them.

Fast diagnosis playbook

When users complain that “code blocks are slow” or “copy doesn’t work,” don’t debate aesthetics. Triage like an incident.

First: confirm the failure mode in 60 seconds

• Copy correctness: click copy, paste into a plain text editor, inspect for line numbers/prompts/odd whitespace.
• Browser console: look for clipboard permission errors or CSP violations.
• Page performance: open devtools performance, reload, look for long tasks around highlighting/hydration.

Second: locate the bottleneck

• CPU bound: many ms in JS execution → likely client-side highlighting, per-line DOM, or expensive selectors.
• DOM bound: layout/recalc style dominates → too many nodes, heavy CSS, line wrapping logic.
• Network bound: huge JS bundles or font files → highlighter or language packs shipped unnecessarily.

Third: apply a surgical fix, not a rewrite

• Move highlighting to build/SSR.
• Reduce languages shipped.
• Stop wrapping lines above a threshold.
• Copy from source string, not DOM.
• Add visual prompts via CSS pseudo-elements or separate spans excluded from copy payload.

Practical tasks with commands, outputs, and decisions

These are the kinds of checks you run when code blocks misbehave. Each task includes a command, what the output means, and what decision you make from it. The commands assume you’re working on a Linux host where the docs site or build runs.

Task 1: Verify Node and package manager versions (reproducibility)

cr0x@server:~$ node --version
v20.11.1

Output meaning: you’re on Node 20; clipboard polyfills and build toolchains behave differently across major versions.

Decision: pin Node in CI (and locally via tooling) if you see inconsistent highlighting output across environments.

Task 2: Measure build-time highlighting cost (is it the bottleneck?)

cr0x@server:~$ /usr/bin/time -v npm run build
...
User time (seconds): 58.23
System time (seconds): 6.12
Percent of CPU this job got: 342%
Elapsed (wall clock) time: 0:18.74
Maximum resident set size (kbytes): 912344

Output meaning: lots of CPU, ~900MB RSS. Highlighters like Shiki can be memory-hungry with many pages/languages.

Decision: cache highlighted output and limit supported languages; if RSS threatens CI containers, split builds or precompute.

Task 3: Find the heaviest pages by code block count (risk hotspot)

cr0x@server:~$ rg -n "```" -S docs/ | cut -d: -f1 | sort | uniq -c | sort -nr | head
  84 docs/runbooks/storage/zfs-replace-disk.md
  62 docs/runbooks/kubernetes/etcd-restore.md
  51 docs/platform/nginx/hardening.md

Output meaning: these files have the most fenced code blocks.

Decision: load-test these pages first; optimize the worst offenders before chasing marginal wins elsewhere.

Task 4: Confirm your rendered HTML isn’t copying line numbers (quick sanity check)

cr0x@server:~$ rg -n "data-line-number|class=\"line-number\"" -S dist/ | head
dist/runbooks/storage/zfs-replace-disk/index.html:412: 1
dist/runbooks/storage/zfs-replace-disk/index.html:413: 2

Output meaning: line numbers are real text nodes/spans, which may end up in selection/clipboard.

Decision: move to CSS counters or separate gutter that’s excluded from selection/copy, or ensure the copy path uses raw code, not DOM text.

Task 5: Detect suspicious Unicode in snippets (clipboard correctness)

cr0x@server:~$ python3 -c 'import sys,unicodedata; s=open("docs/runbooks/kubernetes/etcd-restore.md","r",encoding="utf-8").read(); bad=[c for c in s if unicodedata.category(c) in ("Cf",)]; print(len(bad), sorted(set(hex(ord(c)) for c in bad))[:10])'
3 ['0x200b', '0x2060']

Output meaning: format characters (zero-width space, word joiner) exist. They can break pasted commands.

Decision: add a pre-commit hook or CI lint that rejects these characters in docs, or at least flags them.

Task 6: Confirm the JS bundle isn’t shipping 40 languages (weight control)

cr0x@server:~$ ls -lh dist/assets | sort -k5 -h | tail
-rw-r--r-- 1 cr0x cr0x  84K app.css
-rw-r--r-- 1 cr0x cr0x 312K app.js
-rw-r--r-- 1 cr0x cr0x 1.8M highlight.bundle.js

Output meaning: the highlighter bundle dominates your JS payload.

Decision: switch to build-time highlighting or tree-shake languages; don’t accept a 1.8MB tax for pretty colors.

Task 7: Check for CSP violations affecting clipboard

cr0x@server:~$ rg -n "Content-Security-Policy" -S nginx/conf.d/docs.conf
12:add_header Content-Security-Policy "default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self';" always;

Output meaning: inline scripts are blocked; if your copy button relies on inline handlers, it will fail silently.

Decision: move copy logic into external JS, avoid inline event attributes, or add a nonce-based policy if needed.

Task 8: Validate that build output has stable anchors for line highlights

cr0x@server:~$ rg -n "data-highlight|data-line" -S dist/runbooks/storage/zfs-replace-disk/index.html | head
615: 


Output meaning: highlight metadata is present in the HTML; your client can style it without re-tokenizing.
Decision: keep highlight ranges as data attributes; avoid recomputing line maps in the browser.
Task 9: Identify oversized code blocks that should be “view raw”
cr0x@server:~$ awk 'BEGIN{in=0; n=0} /^```/{in=!in; if(!in){print n; n=0}} {if(in) n++}' docs/runbooks/storage/zfs-replace-disk.md | sort -nr | head
412
188
141

Output meaning: there’s a 412-line snippet; not huge, but it’s a candidate for performance issues if you wrap every line.
Decision: set a threshold (e.g., 200–500 lines) where line-level DOM is disabled or switched to a lightweight mode.
Task 10: Confirm gzip/brotli is enabled (network bottlenecks)
cr0x@server:~$ nginx -T 2>/dev/null | rg -n "gzip|brotli" | head
gzip on;
gzip_types text/plain text/css application/javascript application/json image/svg+xml;

Output meaning: gzip is on; if your JS is still heavy, compression helps but doesn’t fix CPU cost.
Decision: keep compression, but focus on reducing JS and DOM rather than celebrating smaller transfers.
Task 11: Spot-check for per-line DOM explosions (DOM node proxy)
cr0x@server:~$ rg -n "class=\"line\"" -S dist/runbooks/kubernetes/etcd-restore/index.html | wc -l
6220

Output meaning: thousands of per-line elements were emitted.
Decision: stop emitting per-line wrappers for large blocks; use CSS counters or a single tokenized block.
Task 12: Check Lighthouse CLI for page regressions (automation-friendly)
cr0x@server:~$ lighthouse dist/runbooks/kubernetes/etcd-restore/index.html --quiet --chrome-flags="--headless" --only-categories=performance
Performance: 62

Output meaning: performance score is mediocre; code blocks are common culprits due to heavy JS or DOM.
Decision: profile the page; if long tasks correlate with highlighting, move work to build-time and reduce DOM complexity.
Task 13: Verify prompts aren’t being baked into copy payloads
cr0x@server:~$ rg -n "cr0x@server:~\\$" -S dist/ | head
dist/runbooks/storage/zfs-replace-disk/index.html:618: cr0x@server:~$ zpool status

Output meaning: prompt strings appear in rendered HTML. That’s fine visually, risky if your copy logic scrapes DOM text.
Decision: store a separate raw command string for copying, or mark prompt spans with data-no-copy and enforce it in copy logic.
Task 14: Confirm no secrets are embedded in code blocks (yes, people do this)
cr0x@server:~$ rg -n "AKIA|BEGIN PRIVATE KEY|password\s*=" -S docs/ | head
docs/runbooks/app/deploy.md:203: password = "changeme"

Output meaning: there are suspicious patterns; sometimes they’re examples, sometimes they’re real secrets.
Decision: enforce redaction rules; for real environments, use placeholders and a secret management workflow, not inline credentials.

Three corporate mini-stories from the trenches

Mini-story 1: The incident caused by a wrong assumption

The company had an internal “Engineering Handbook” that everyone used. It looked modern: clean typography, fancy code blocks, and a copy button. A team rolled out a migration guide for rotating database credentials, with about a dozen shell commands.

Someone assumed prompts were harmless. The author wrote examples like dbadmin@bastion:~$ psql ... and the renderer stored exactly that in the code block’s text node. The copy button copied what it saw.

It worked for people who pasted into a shell that ignored the junk because they manually removed the prompt. It failed for automation. A few engineers, doing the rotation under time pressure, pasted the whole thing into a non-interactive shell runner that treats unknown tokens as commands. The first token was dbadmin@bastion:~$. The runner failed fast, but the workflow didn’t. It interpreted failure as “try the next step.”

The end result wasn’t catastrophic, but it was loud: partial changes, confusing logs, and one database user locked out earlier than intended. The post-incident analysis was embarrassing because the root cause wasn’t PostgreSQL or IAM. It was a docs UI widget that copied the wrong bytes.

Fixing it was straightforward: prompts became visual-only spans, copy used a prompt-free payload, and the docs build started linting for prompt patterns in “copyable” blocks. The interesting part was cultural: after that, the docs team got invited to incident reviews. They earned it.

Mini-story 2: The optimization that backfired

A different org decided their docs site should support “live theme switching” between light and dark without reloading. They switched from build-time highlighting to client-side highlighting so the browser could recolor tokens dynamically.

On paper, it sounded clean: ship raw code, run Prism in the browser, apply CSS themes. In practice, the docs site had long runbooks with many code blocks, some of them large (Kubernetes manifests, incident timelines, log excerpts). Every page load did tokenization work on the main thread.

They noticed the performance hit and tried to optimize. The “optimization” was to wrap every line in a span so line highlighting and line numbers could be done with simple CSS. That increased DOM nodes massively. The browser spent more time in style recalculation and layout than in highlighting itself.

Then came the real kicker: on lower-end laptops and some VDI setups, scrolling became choppy. People started copying code less because the UI felt unreliable. The project achieved theme switching and lost trust—a bad trade.

The rollback was pragmatic. They kept theme switching for the page chrome, but code blocks became build-time highlighted again with two precomputed themes. Theme switch swapped a class and CSS variables; the code blocks used pre-rendered token spans. It wasn’t “pure.” It was fast and stable. That’s what mattered.

Mini-story 3: The boring, correct practice that saved the day

A financial services company maintained strict internal runbooks. The docs were static, built in CI, and published behind authentication. Nothing fancy. What they did have was a brutal lint pipeline.

Every pull request ran a docs check that validated code fences: languages had to be recognized, line highlight ranges had to be valid, and forbidden characters (zero-width spaces, non-breaking spaces in commands) were blocked. It also checked that terminal blocks used a consistent prompt format and provided a prompt-free copy payload.

One week, a vendor sent them a “fix script” embedded in a PDF. An engineer copied it into a runbook. The script contained a non-breaking space between a flag and its argument—visually indistinguishable in the editor they used. The linter caught it immediately, failed the build, and printed the Unicode code point.

The engineer grumbled, replaced the character, and moved on. Two days later, the script was executed during a live incident. It worked. Nobody thought about the linter again, which is the highest compliment for boring correctness.

That pipeline wasn’t glamorous. It didn’t win design awards. It prevented a class of failures that only show up under stress. In ops, that’s a win.

Common mistakes: symptoms → root cause → fix

This is the section you’ll recognize in hindsight. Save yourself the hindsight.

1) “Copy” includes line numbers

• Symptoms: pasted code starts with 1, 2, or has numbers at the start of each line; commands fail.
• Root cause: line numbers are inserted as actual text nodes/spans inside the selectable region; copy logic scrapes innerText.
• Fix: copy from the model’s raw code string; render line numbers via CSS counters or separate gutter excluded from selection.

2) Copy button does nothing in production but works locally

• Symptoms: no error shown; users report “copy button dead.”
• Root cause: CSP blocks inline scripts or event handlers; clipboard API requires secure context; permissions differ.
• Fix: move logic to external JS; ensure HTTPS; add telemetry for copy failures and expose a fallback “select code” affordance.

3) Highlighted lines are off by one

• Symptoms: author highlights line 5, but UI highlights line 4 or 6.
• Root cause: mismatch between how lines are counted (leading newline, trimming, CRLF vs LF) or parser counts from 0 while UI counts from 1.
• Fix: normalize line endings at ingestion; define line numbering as 1-based; add tests for edge cases (leading newline, trailing newline).

4) Scrolling and typing lag on pages with big code blocks

• Symptoms: jank, slow scroll, high CPU, fans spin.
• Root cause: client-side highlighting and/or per-line DOM wrappers creating thousands of nodes; heavy CSS selectors.
• Fix: do highlighting at build/SSR; cap per-line DOM; simplify CSS; use virtualization only if you really must render huge blocks.

5) Users copy commands but get smart quotes or broken dashes

• Symptoms: flags look correct but shell errors; pasted text contains weird punctuation.
• Root cause: typography transforms or rich text editors introduced replacements (en-dash vs hyphen, curly quotes).
• Fix: ensure code blocks are plain text; lock down editors; lint for suspicious Unicode in code fences.

6) Find-in-page doesn’t match code

• Symptoms: browser search can’t find a string visible in code block.
• Root cause: tokenization inserts spans splitting text; some search implementations struggle, or content is rendered via canvas/virtual DOM weirdness.
• Fix: keep code as actual text nodes in the DOM; don’t render code via canvas; avoid aggressive DOM restructuring.

7) Line numbers break wrapping and overflow

• Symptoms: code overlaps gutter; horizontal scroll is broken; numbers misalign.
• Root cause: gutter width not reserved; font metrics differ between gutter and code; inconsistent line-height.
• Fix: use a two-column layout with fixed gutter width; enforce same font and line-height; test on multiple platforms.

Checklists / step-by-step plan

Step-by-step: build a GitHub-style code block component that won’t betray you

1. Pick a rendering strategy. Prefer build-time or SSR highlighting for docs; avoid client-side tokenization unless content is truly dynamic.
2. Define the code block model. language, title, raw code, highlight ranges, showLineNumbers, kind, copy payload.
3. Normalize input. Convert CRLF to LF, keep tabs, preserve trailing spaces where meaningful, and reject format characters in CI.
4. Implement the display path. Render title bar + code; keep code text in a stable DOM structure.
5. Implement line numbers safely. CSS counters or separate gutter; never inject numbers into the code text.
6. Implement highlighted lines deterministically. Parse “1,3-5” ranges; validate; highlight logical lines only.
7. Implement copy using stored payload. Don’t scrape DOM; handle clipboard failures with a fallback (select + manual copy).
8. Add accessibility. Keyboard focus, aria labels, live region feedback, sufficient contrast for highlights.
9. Set performance guardrails. Hard caps on per-line DOM; “view raw” mode for huge blocks; limit language bundles.
10. Add telemetry. Copy success/failure, highlight parse errors, page performance marks on heavy pages.
11. Write tests. Snapshot tests for HTML structure; unit tests for range parsing; e2e tests for copy payload.
12. Document authoring rules. How to specify titles, prompts, and highlights; what gets copied; what doesn’t.

Pre-merge checklist for docs authors (the human layer)

• Did you mark terminal prompts as display-only?
• Is there any “smart punctuation” inside code fences?
• Are highlighted lines within the block length?
• Are you shipping secrets, tokens, or real hostnames that should be placeholders?
• Is the code block too large for a page? Should it be a file download?
• Did you try the copy button and paste into a plain text editor?

Ops checklist: when you roll out changes to code block rendering

• Can you roll back the renderer independently of content?
• Are caches keyed by highlighter version and theme?
• Do you have a canary page with worst-case code blocks to test performance?
• Is CSP enforced in staging exactly like production?
• Do you alert on JS errors affecting copy interactions?

FAQ

1) Should I always add line numbers?

No. Add them when the snippet is referenced by line in the surrounding text, or when it’s long enough to benefit. For 5-line commands, line numbers are noise.

2) How do I prevent line numbers from being copied?

Don’t render them as part of the code text. Use CSS counters or a separate gutter. And copy from a stored raw string, not innerText.

3) Should prompts be included in code fences?

Visually, yes—prompts communicate “this is a command.” In the copy payload, usually no. If you must support both, offer two copy modes.

4) Why not just use client-side Prism everywhere?

Because it pushes CPU and JS costs to every reader, on every page view. For docs, that’s a long-term tax you don’t need to pay if you can pre-render.

5) What’s the cleanest way to support a title bar in Markdown?

Use a conventional metadata syntax your parser can read (like an info string extension) and map it into your code block model. Don’t parse title bars from comments inside code.

6) How do highlighted lines interact with wrapped lines?

They shouldn’t. Highlight logical lines only. Wrapping is a presentation detail and varies by viewport, font, and user settings.

7) How do I handle huge code blocks (logs, generated files)?

Don’t render them as a fully tokenized, per-line DOM. Provide a truncated preview and a “view raw” download. Keep the page fast.

8) What about accessibility—do code blocks need ARIA?

The code block itself should remain standard HTML (<pre><code>). The copy button needs proper labeling, keyboard focus, and non-intrusive feedback via an aria-live region.

9) Why do my highlighted lines shift between environments?

Usually line-ending normalization (CRLF vs LF) or trimming differences. Normalize at ingestion, and test with fixtures that include Windows line endings.

10) Can I safely instrument copy events?

Yes—log metadata only. Never log the copied content. Assume snippets may contain secrets even when they “shouldn’t.”

Next steps that actually ship

If you want GitHub-style code blocks without turning your docs platform into a science project, do this in order:

1. Define the component contract (model fields, copy payload rules, highlight range rules).
2. Move highlighting off the client unless you have truly dynamic content.
3. Implement copy from source, not from rendered DOM text.
4. Set performance guardrails (max lines for per-line rendering, max languages shipped).
5. Lint docs content for Unicode hazards, invalid highlight ranges, and prompt usage.
6. Instrument copy failures and page performance on your worst runbooks.

Then ship it. Watch the metrics. If you’re not seeing fewer “docs broke my command” pings, your copy path is still lying to someone.