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

DebugSteven · 2025-08-06T22:16:01Z

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-render, this adds copyToClipboard to the properties on BlockType.codeListing.
Adds a copy-to-clipboard button in CodeListing.vue, similar to swift.org’s copy-to-clipboard button on its code blocks, when copyToClipboard is set to true from the feature flag enable-experimental-code-block. Includes a function, copyCodeToClipboard, to copy the contents of a code block to clipboard.
Adding ```nocopy disables the copy button on that code block.
This flag is forwarded from swift-docc. The accompanying branch/PR is here: Add copy-to-clipboard support to code blocks swift-docc#1273

Dependencies

This PR depends on associated changes in swift-docc to pass the parameter for 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

Added tests
Ran npm test, and it succeeded
Updated documentation if necessary – On my DocC PR I added a subsection to Formatting Your Documentation Content, along with updating RenderNode.spec.json to include copyToClipboard as a property on CodeListing. Please let me know if there's any other documentation I should update here.

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

@swift-ci please test

mportiz08

Hi @DebugSteven :) I'm really excited to see you bringing this functionality to DocC and DocC-Render, and I especially love the minimal/additive syntax proposed to make this a progressive, opt-in enhancement for DocC code listings.

Unfortunately, I'm about to be offline for a week, so I won't have time to properly test/review this PR during that time.

However, I took a brief look at the implementation and have a suggestion for a simpler way to position the icon/button that maybe you could explore—I promise to take a more complete look at this PR when I'm back online either way—sorry again for the bad timing on my end!

mportiz08 · 2025-08-06T23:13:52Z

src/components/ContentNode/CodeListing.vue

@@ -122,6 +170,43 @@ export default {
        line === '' ? '\n' : line
      ));
    },
+    updateCopyButtonPosition() {


I'm thinking there might be a simpler way to position this element using pure CSS that would eliminate the need for refs and any custom JS listening to events, etc

As a very basic example, this is some minimal CSS that could be used to position a small red box with the letter "A" in the top-right corner of a given code listing. Maybe you could check this out and explore a CSS based solution to the layout and position for the icon/button to avoid the need for scroll event listeners?

diff --git a/src/components/ContentNode/CodeListing.vue b/src/components/ContentNode/CodeListing.vue index 8f1524fc..ba7ceebc 100644 --- a/src/components/ContentNode/CodeListing.vue +++ b/src/components/ContentNode/CodeListing.vue @@ -129,6 +129,19 @@ export default { <style scoped lang="scss"> @import 'docc-render/styles/_core.scss'; +.code-listing::after { + align-items: center; + background: red; + color: white; + content: 'A'; + display: flex; + height: 25px; + justify-content: center; + position: absolute; + right: 0; + width: 25px; +} + .code-line-container { display: inline-block; width: 100%;

(The important pieces there being the position: absolute and right: 0)

Thank you for this suggestion! I'll try to get the button positioning working with pure CSS and I'm glad it's feasible. I was concerned about the performance implications with the scroll event listeners.

heckj · 2025-08-12T22:41:00Z

@swift-ci please test

mportiz08

This is looking really great! I'm glad that the absolute positioning approach simplified things and is working out well.

I have some feedback after looking this over more closely and testing it out, but my comments are mostly pretty minor suggestions.

Thank you so much for looking into this!

mportiz08 · 2025-08-13T22:28:32Z

src/components/ContentNode/CodeListing.vue

+        @click="copyCodeToClipboard"
+        aria-label="Copy code to clipboard"
+      >
+        <svg


It would be great if we could extract both of these icons to their own Vue components, similar to how it has been done for other svg icons.

There isn't anything wrong with how you've done it inline here, but with the components we could more easily re-use them in other places at a later point, and we could introduce a customization point so the actual assets would be easier to swap with theming as well.

I separated the icons into separate components like you asked. However, I couldn’t get them to work with the SVGIcon component without messing up the CSS. Is there a trick I'm missing?

src/components/ContentNode/CodeListing.vue

mportiz08 · 2025-08-13T22:40:34Z

src/components/ContentNode/CodeListing.vue

+        class="copy-button"
+        :class="{ copied: isCopied }"
+        @click="copyCodeToClipboard"
+        aria-label="Copy code to clipboard"


Can we extract the "Copy code to clipboard" string to a new key-value pair in src/lang/locales/en-US.json so that we could more easily translate this text for other languages in the future?

I added the string to en-US.json, but I’m not entirely sure it’s added correctly. Could you double check and adjust if needed or let me know the correct approach?

mportiz08 · 2025-08-13T22:52:30Z

src/components/ContentNode/CodeListing.vue

+          }, 1000);
+        })
+        .catch(err => (
+          console.error('Failed to copy text: ', err)


This is a pretty minor detail since I think this API is pretty well supported at this point, but I wonder if we should also show a failure icon in the UI to make this failure less silent/hidden?

Just pseudo code, but maybe it could be something like:

async copyCodeToClipboard() { try { await navigator.clipboard.writeText(copyableText); this.copyingState = CopyingState.succeeded; } catch (err) { console.error(...); this.copyingState = CopyingState.failed; } finally { this.setTimeout(() => { this.copyingState = null; }, duration); } }

(The state could then just be used to toggle which version of the icon to show at any given time)

This probably isn't a blocking issue since the copy functionality is pretty widespread at this point and unlikely to fail—just thinking out loud mostly.

mportiz08 · 2025-08-13T22:54:10Z

src/components/ContentNode/CodeListing.vue

+  position: absolute;
+  top: 0.2em;
+  right: 0.2em;
+  width: 24px;


Potentially we could size this using em units like 1em to have the icon or button size match the size of the code listing text itself so it scales as users adjust the font-size on their browsers.

I think this size looks pretty good though if we want to leave it hardcoded to 24px—just a thought.

I changed the width/height to be 1.5em because I thought that would be equivalent to 24px. Let me know if you were thinking of doing this differently.

src/components/ContentNode/CodeListing.vue

mportiz08 · 2025-08-13T23:04:51Z

src/components/ContentNode/CodeListing.vue

@@ -22,6 +22,33 @@
    >{{ fileName }}
    </Filename>
    <div class="container-general">
+      <button


Design-wise, I think the button can be a little distracting for code listings with a long first-line of code since the button always shows directly over the text (when enabled).

If we were to enable this button by default for code listings (which I personally think would be great), we may want to consider only showing it when hovering over the listing to try and eliminate some of that distraction maybe? That's just my personal opinion though. We could also consider a different layout where the button doesn't appear directly over the text as an alternative, although the positioning could get tricky in that case.

As a concrete example, 2 of the 3 code listings on this screenshot from the PR description are obscured by the button, regardless of where the user focus is:

I agree that it’s nicer to show the copy button only when hovering over code blocks. Originally I had the button only show when hovering over code blocks. However, Joe and I got some feedback on the forums that it’d be better for mobile use to have the button always visible.

I think I’ve got a decent solution here in my latest commit. I’m using @media (hover: hover) for devices that support hover and I added @media (hover: none), when hover isn’t supported, to set the button to be always visible. Let me know what you think.

Just to share the same pictures from the forums, here's what those changes look like on desktop and mobile.

Jesse Haigh added 5 commits August 1, 2025 10:49

code copying functionality on code listings

5b424bb

style, very similar to swift.org's code block copy style

69a9d40

use color variables

9fe7c28

update copy button position on code block scroll

c2abb95

tests

cce81b7

DebugSteven mentioned this pull request Aug 6, 2025

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

Open

3 tasks

mportiz08 reviewed Aug 6, 2025

View reviewed changes

Jesse Haigh added 2 commits August 7, 2025 14:08

position copy button relative to code listing with CSS

17f7572

modify position/padding on copy button to fit on single line code blocks

14914c2

DebugSteven force-pushed the codeblock-copy branch from 51054a0 to 14914c2 Compare August 7, 2025 20:11

Jesse Haigh added 3 commits August 11, 2025 12:12

copy by default

09210b6

reduce copy button opacity to show contents behind button

97352b7

default to false for copyToClipboard

a5c7019

mportiz08 reviewed Aug 13, 2025

View reviewed changes

address (most) feedback

75c56fc

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

Are you sure you want to change the base?

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

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!

mportiz08 left a comment

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!

heckj commented Aug 12, 2025

Uh oh!

mportiz08 left a comment

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!

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!

Uh oh!

DebugSteven commented Aug 6, 2025 •

edited

Loading