Add copy-to-clipboard support to code blocks

[DebugSteven]

Summary

This PR adds support for a new copy-to-clipboard button in code blocks. When this feature is enabled through the enable-experimental-code-block flag, a copy-to-clipboard button is rendered in the top-right corner of all code blocks, allowing users to easily copy its contents. When an author does not want the contents of a code block to be copyable, a nocopy option can be used to disable the copy-to-clipboard button.

User Experience

When the enable-experimental-code-block flag is used, a copy button will appear in the top-right corner of all code blocks. Clicking the button copies the full contents of the code block to the clipboard and displays a checkmark to confirm success. If a code block includes the nocopy keyword in the language line, the copy button will not appear on that code block.

Implementation Overview

• In swift-docc, this change adds a feature flag enable-experimental-code-block, which enables a copy-to-clipboard button on code blocks by default.
• Parses the nocopy option from the language line in triple-backtick code blocks to disable the copy button on that code block.
• A copyToClipboard property was added to RenderBlockContent.codeListing passed to the renderer.
• This flag is forwarded to swift-docc-render. The accompanying branch/PR is here: Add copy-to-clipboard support to code blocks swift-docc-render#961

Dependencies

This PR depends on associated changes in swift-docc-render to actually render and handle the copy button.

Testing

Setup

1. Use the codeblock-copy branches for swift-docc and swift-docc-render with the copy-to-clipboard changes.
2. Rebuild documentation using swift-docc with the feature flag enable-experimental-code-block and serve it using a local build of swift-docc-render.

How to Test

1. In all code listings with the enable-experimental-code-block flag, a copy button will appear in the top-right corner.
2. Click the copy icon. The code should be copied to your clipboard and the icon should update to a checkmark briefly. Paste to verify the copy functionality works.

To disable the copy icon with the feature flag enabled:

1. In any code listing using ``` or by adding a code listing, add the nocopy option like this:

```swift, nocopy
print(“Hello, world!”)
```


or like this:


```nocopy
print(“Hello, world!”)
```


2. Verify the copy button does not appear on this code block.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests – testCopyToClipboard() in RenderContentCompilerTests.swift
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary – I added copyToClipboard as a property of CodeListing in RenderNode.spec.json. I also added a subsection to Formatting Your Documentation Content. Please let me know if there’s any other documentation I should update.

Shown with cursor hovering over the 2nd copy-to-clipboard button on screen:

Shown with a narrow viewport:

Screen.Recording.2025-08-11.at.5.00.31.PM.mov

[heckj]

@swift-ci please test

[d-ronnqvist]

Since this is adding new user-facing syntax I'm adding the needs-forum-discussion tag until the community has had time to discuss the new syntax.

[d-ronnqvist]

There is a forum thread for this here. It would be good for that thread to cover some discussion on future directions so that we feel comfortable that this syntax can scale to accommodate those future directions (or intentionally not support them if we believe that each would benefit from a different user-facing syntax).