Add copy-to-clipboard support to code blocks #1273

DebugSteven · 2025-08-06T21:50:12Z

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

Use the codeblock-copy branches for swift-docc and swift-docc-render with the copy-to-clipboard changes.
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

In all code listings with the enable-experimental-code-block flag, a copy button will appear in the top-right corner.
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:

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.

heckj · 2025-08-06T22:32:50Z

@swift-ci please test

d-ronnqvist · 2025-08-07T10:10:27Z

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 · 2025-08-07T10:18:35Z

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).

…mited by commas

…rd and other code block annotations

heckj · 2025-08-12T22:40:51Z

@swift-ci please test

d-ronnqvist

Thanks for opening this PR.

The code looks good to me with some questions about how nocopy option should work when the feature flag isn't enabled. If the current behavior is intended then that code doesn't need to change.

I have some non-blocking feedback on the developer-facing documentation for this. Because the feature flag help-text mentions additional features that aren't added in this PR I suspect that this documentation (and possibly also the syntax) could frequently as more features are added. If you are fine with updating (and possibly rewriting parts of) the documentation as new experimental features as added, then you can keep it in the pull request. An alternative would be to write the documentation when removing the experimental status from these features, when the scope and syntax has settled.

Sources/SwiftDocC/Semantics/Snippets/Snippet.swift

d-ronnqvist · 2025-08-14T11:50:03Z

Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

+            struct ParsedOptions {
+                var lang: String?
+                var nocopy = false
+            }
+
+            func parseLanguageString(_ input: String?) -> ParsedOptions {
+                guard let input else { return ParsedOptions() }
+
+                let parts = input
+                    .split(separator: ",")
+                    .map { $0.trimmingCharacters(in: .whitespaces) }
+
+                var options = ParsedOptions()
+
+                for part in parts {
+                    let lower = part.lowercased()
+                    if lower == "nocopy" {
+                        options.nocopy = true
+                    } else if options.lang == nil {
+                        options.lang = part
+                    }
+                }
+                return options
+            }
+
+            let options = parseLanguageString(codeBlock.language)


If I understand correctly, I think that we'd want to parse the code block's languages string into its components even when the feature flags is not enabled. Otherwise, a string like swift, nocopy wouldn't produce the any syntax highlighting unless the developer also passes the feature flag.

I feel like i have the opposite opinion here. If someone has written swift,nocopy, then they are explicitly aware of this feature flag and should be required to enable it to maintain the expected behavior. Otherwise they're writing a "weird language flag" that we would otherwise know nothing about.

A way we can soften the blow of working with this is to add this feature flag to BundleFeatureFlags to allow it to be set in Info.plist, like i did with the overloaded-symbol presentation in #891. That way, authors can set the feature flag in the same commit that they start to use the nocopy flags, and it should Just Work™.

That's fair. I can imagine different people being surprised about both behaviors.

@DebugSteven has already added this flag to BundleFeatureFlags, so that seems like a good way for people to adopt this while this feature is experimental.

As a mental note for myself and @QuietMisdreavus:
Looking at the BundleFeatureFlags code now, we will at some point need to figure out a strategy for deprecating and migrating an experimental flag in the Info.plist to its non-experimental replacement. We haven't needed to do so yet, but it's kind of weird that the container key includes the word "experimental" if it can contain non-experimental flags.

Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md

d-ronnqvist · 2025-08-14T12:12:55Z

Tests/SwiftDocCTests/Rendering/RenderContentCompilerTests.swift

@@ -223,4 +223,52 @@ class RenderContentCompilerTests: XCTestCase {
            XCTAssertEqual(documentThematicBreak, thematicBreak)
        }
    }
+
+    func testCopyToClipboard() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockEnabled)


Question: is there a corresponding test that checks that code listings don't have a copy-to-clipboard button when the feature flag isn't set? This could be as small as adding XCTAssertEqual(codeListing.copyToClipboard, false) to some existing test.

I didn't see tests that already had Code Listings on them, so I opted to add a new test. If there's a place you'd prefer me to add this assertion, let me know and I can do that instead.

d-ronnqvist · 2025-08-14T12:13:45Z

Tests/SwiftDocCTests/Rendering/RenderContentCompilerTests.swift

+    }
+
+    func testNoCopyToClipboard() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockEnabled)


Question: Do we want to test the behavior when a code block contains swift, nocopy but the feature flag isn't enabled?

I added another test for this as well. It shows that when the feature flag isn't enabled and a code block contains swift, nocopy that codeListing.syntax will equal the contents of the entire line, swift, nocopy in this case. Let me know if there is more I should do on that test.

Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md

features.json

Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift

d-ronnqvist · 2025-08-14T12:47:45Z

Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

+                var nocopy = false
+            }
+
+            func parseLanguageString(_ input: String?) -> ParsedOptions {


Do we have any plans to raise diagnostics here if we encounter an unknown option?

For example, the code below will parse swift, nocpoy as lang: nocpoy, nocopy: false and the only way for the developer to notice this is to see that the rendered code listing has a copy-to-clipboard button and doesn't have syntax highlighting.

If we want the possibility of raising diagnostics from this (or future) code block options, it probably needs be parsed earlier in the build, before "rendering".

I think it would be a good idea to raise diagnostics for unknown options. I’m not familiar with DocC diagnostics and I don’t understand why it would need to be emitted earlier. Could you give me some more info?

DebugSteven mentioned this pull request Aug 6, 2025

Add copy-to-clipboard support to code blocks swiftlang/swift-docc-render#961

Open

3 tasks

d-ronnqvist added the needs forum discussion Needs to be discussed in the Swift Forums label Aug 7, 2025

heckj self-assigned this Aug 7, 2025

DebugSteven force-pushed the codeblock-copy branch from c89047e to d0b75d8 Compare August 7, 2025 21:40

Jesse Haigh added 8 commits August 11, 2025 10:32

WIP add copy button to CodeListing

53ee456

update OpenAPI spec with copyToClipboard on CodeListing

753c0dc

Add option to copy a code block parsed from the language string, deli…

12b2d50

…mited by commas

fix unit tests

39d2ad3

add unit test for copyToClipboard

8ce67d3

fixup missing async on test

08bd353

update docs

bb50fb9

copy by default

1f4894d

DebugSteven force-pushed the codeblock-copy branch from d0b75d8 to 1f4894d Compare August 11, 2025 17:20

add feature flag 'enable-experimental-code-block' for copy-to-clipboa…

3ae43b1

…rd and other code block annotations

d-ronnqvist reviewed Aug 14, 2025

View reviewed changes

add more tests, remove docs, code cleanup

2cf5ac1

Add copy-to-clipboard support to code blocks #1273

Are you sure you want to change the base?

Add copy-to-clipboard support to code blocks #1273

Conversation

DebugSteven commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

User Experience

Implementation Overview

Dependencies

Testing

Setup

How to Test

Checklist

Uh oh!

heckj commented Aug 6, 2025

Uh oh!

d-ronnqvist commented Aug 7, 2025

Uh oh!

d-ronnqvist commented Aug 7, 2025

Uh oh!

heckj commented Aug 12, 2025

Uh oh!

d-ronnqvist left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DebugSteven Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DebugSteven commented Aug 6, 2025 •

edited

Loading

DebugSteven Aug 15, 2025 •

edited

Loading