Your docs can look right and still copy wrong

Lidong Wang — Tue, 01 Sep 2026 10:54:23 +0000

A code block can look perfectly correct while its Copy button silently changes what reaches the clipboard.

The failures are usually small enough to escape screenshots and ordinary DOM assertions:

a final newline disappears;
tabs become spaces;
indentation is trimmed;
a shell prompt is removed;
ASCII punctuation becomes a Unicode look-alike;
composed and decomposed Unicode compare differently.

For a command that will be pasted into a terminal, “almost the same” is not a useful contract.

Why a DOM assertion is not enough

Most documentation tests stop at the rendered <code> element. Copy behavior introduces at least two more boundaries:

canonical source -> rendered DOM -> copy handler -> browser clipboard

A page can render the right text but send a different string to navigator.clipboard.writeText. The handler can also send the right string while the browser or operating system exposes a transformed result. Without observing the stages separately, a failure is easy to misattribute.

That is the narrow problem I built Snippet Fidelity to test.

A one-step reconnaissance check

The fastest way to try it is a GitHub Actions workflow against a public documentation page:

name: snippet-fidelity

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: WLDKK/snippet-fidelity@v0
        with:
          url: https://docs.example.com/getting-started/

This mode discovers visible copy controls near code blocks, activates them in real Chromium, and compares copied text with the rendered code. It is useful reconnaissance, but it cannot prove that the rendered page matches a maintainer's source of truth.

Turn it into a release gate

For a dependable contract, point a check at a checked-in UTF-8 source file:

{
  "$schema": "https://raw.githubusercontent.com/WLDKK/snippet-fidelity/v0/schema/config.schema.json",
  "version": 1,
  "baseUrl": "https://docs.example.com/",
  "pages": [
    {
      "url": "getting-started/",
      "checks": [
        {
          "id": "install-command",
          "button": "#install-command button[aria-label='Copy code']",
          "expected": { "file": "./snippets/install.sh" },
          "probe": "both"
        }
      ]
    }
  ]
}

Now the result can distinguish a source-to-render mismatch from a handler or clipboard mismatch. Reports use SHA-256 fingerprints, lengths, categorized findings, and a bounded escaped context around the first different Unicode code point. Full snippets are not printed by default.

What real-site testing taught me

I ran the discovery mode against three maintained documentation sites. Three Starlight checks matched. Material for MkDocs consistently omitted a rendered terminal newline, while Doc Detective omitted a displayed shell prompt marker.

Those differences may be deliberate paste-friendly behavior. I do not label them bugs, because rendered-page discovery does not know the maintainers' canonical intent. That result led to an important reporting rule: a mismatch is an observation; a release-blocking claim requires a maintainer-owned source contract.

The pilot also found a bug in the tool itself. Tabbed documentation often keeps inactive code blocks mounted, so the first implementation tried to activate hidden duplicate controls. The fix excluded non-rendered blocks while retaining hover-revealed controls, then added an end-to-end regression fixture.

Reproduce the failure classes locally

The repository includes an adversarial fixture with one passing control and five intentional failures:

pnpm install
pnpm build
pnpm fixture

# In another terminal:
node dist/cli.js audit --config examples/adversarial-fixture.config.json

The expected outcome is one pass and five failures. A zero exit code would mean the fixture stopped exercising the intended regressions.

Scope and limits

Snippet Fidelity is deliberately not a generic documentation testing framework or clipboard manager. It does not execute copied commands, rewrite clipboard content, or claim source fidelity when the baseline came from the rendered DOM. Version 0.4 currently drives Chromium, and automatic discovery remains heuristic; explicit selectors and canonical source are required for a serious release gate.

The project is MIT licensed and available as a GitHub Action and npm package:

Repository: https://github.com/WLDKK/snippet-fidelity?utm_source=devto&utm_medium=article&utm_campaign=v0_4_launch
GitHub Marketplace: https://github.com/marketplace/actions/snippet-fidelity

If you maintain public developer documentation, you can open a public audit request with one page. I am especially interested in examples where whitespace, generated snippets, tabs, or Unicode matter.

Disclosure: I used AI assistance to review wording and test coverage. I verified the implementation, commands, limitations, and reported evidence before publication.

I built a source-to-clipboard test for documentation code blocks

Lidong Wang — Sun, 30 Aug 2026 06:26:12 +0000

A documentation code block can render correctly while its Copy code button silently changes the
text. A trailing newline, a tab converted to spaces, a zero-width character, or Unicode
normalization may be invisible on screen but still matter to a shell command, configuration file,
or source example.

I built Snippet Fidelity to test that narrow boundary:

canonical snippet -> rendered page -> copy handler -> browser clipboard

It drives Chromium, activates the intended copy control, records the
navigator.clipboard.writeText payload when available, reads the browser clipboard, and compares
both observations at Unicode code-point precision.

The repository includes a synthetic adversarial fixture with one valid control and five intentional
regressions. A local run currently produces:

Snippet Fidelity: 1/6 passed, 5 failed, 0 errors.

The failures cover:

terminal newline changes;
indentation loss;
tab/space substitution;
zero-width character injection;
Unicode normalization.

Reports contain fingerprints, lengths, categorized findings, and bounded escaped context around the
first difference. They do not print the complete expected or copied snippet by default.

This is deliberately not a Markdown linter, a generic clipboard manager, or a replacement for broad
documentation test frameworks. A linter checks source; Snippet Fidelity checks what a real rendered
page actually copies. Source-aware configuration can use literal canonical text or an exact UTF-8
file, while discovery mode is useful for reconnaissance.

Quick start:

npm install --save-dev snippet-fidelity
npx playwright install chromium
npx snippet-fidelity audit https://docs.example.com/

There is also a GitHub Action
for source-aware release gates.

I have used the tool to validate copy-button work in two open upstream pull requests:
obsidian-webpage-export #751 and
Nexus #681. Those reviews are ongoing; they are evidence
of real integration work, not claims of upstream adoption.

The project is an early public release (v0.2.0) and Chromium-only today. I would especially value a
minimal public documentation page where the visual code and copied payload disagree—or a report
showing that the tool classified a difference incorrectly. Reproducible counterexamples will shape
the conformance contract more usefully than feature requests in the abstract.

Repository: https://github.com/WLDKK/snippet-fidelity
npm: https://www.npmjs.com/package/snippet-fidelity
Release: https://github.com/WLDKK/snippet-fidelity/releases/tag/v0.2.0

DEV Community: Lidong Wang