A copy button should place on the clipboard exactly the text the reader sees in the code block, with no hidden content, no shell prompt characters and no trailing commands. Anything else breaks trust and can run commands the reader never reviewed. Test it, and keep the copied text identical to the rendered text.
The trust contract
A reader who clicks a copy button is saying "I read this, run it". The button is a promise that the clipboard matches the screen. Break that promise and a docs page becomes a delivery mechanism for commands nobody approved.
Pasting into a terminal is the sharp end of this. Many terminals execute a pasted line as soon as it contains a newline. A hidden extra line in the clipboard text can run before the reader looks.
How copy and display drift apart
| Cause | Result |
|---|---|
| Script builds the clipboard text separately from the visible text | The two differ, sometimes by design, sometimes by bug |
| Prompt characters like a leading dollar sign included | The first word is not a command and the line fails |
| Hidden spans or zero size text inside the block | Extra text is copied but not shown |
| Line wrapping inserted by the theme | A long command is broken into two |
| Smart quotes or dash substitution by the site generator | The pasted command fails or does something unexpected |
Some of these are annoyances. The hidden text case is a security problem, because it lets content that is invisible to the reviewer reach the terminal. Related: can hidden unicode characters hide in copied code.
Rules for your docs site
- Build the clipboard text from the same source string that renders the block, not from a second copy.
- Strip nothing and add nothing. If you show a prompt character, offer a setting that leaves it out of the copy, and test it.
- Keep one logical command per copy action unless the steps truly belong together, and separate steps with visible blank lines.
- Never hide content inside a code block with styling tricks.
- Disable smart punctuation inside code blocks in your site generator.
- Show long commands with continuation characters that work when pasted, rather than relying on theme wrapping.
How to test
Take every code block on a sample of pages and compare three things: the text in the source file, the text rendered on the page, and the text the button copies. A small script that clicks the button in a headless browser and reads the clipboard can do this on every build. Fail the build when they differ.
For multi step shell snippets, paste into a terminal with echo of the content visible, so you can see exactly what arrived.
Guidance for the reader
Even with a trustworthy button, a careful reader pastes into an editor or a text field first, reads it, and then runs it. Docs can encourage this for installers and any command that needs elevated rights. See is curl pipe bash safe for a worked example.
Safeguard's policy gates and dependency scanning protect the code that eventually lands in your repository, whatever its source. Try the free scan at https://gold.safeguard.sh/scan.
Quick check
Is it fine to hide the prompt character from the copy?
Yes, and it is helpful, as long as the visible text and the copied text otherwise match and you test it.
Why not copy extra setup lines for convenience?
Because the reader approves what they see. Extra copied text is text nobody reviewed.
Last reviewed: 19 October 2026.
