Add copy-to-clipboard support for code blocks (with 'nocopy' annotation to disable) (#1273)

* Adds a `copyToClipboard` property on `CodeListing`
* Introduces the `enable-experimental-code-block-annotations` feature
  flag
* Supports disabling copy with the `nocopy` annotation, parsed from
    the code block’s language line
* Updates the OpenAPI spec to include `copyToClipboard`

Co-authored-by: Jesse Haigh <[email protected]>

Author: DebugSteven

Sources/SwiftDocC/Checker/Checkers/InvalidCodeBlockOption.swift

@@ -0,0 +1,62 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+internal import Foundation
+internal import Markdown
+
+/**
+ Code blocks can have a `nocopy` option after the \`\`\`, in the language line.
+`nocopy` can be immediately after the \`\`\` or after a specified language and a comma (`,`).
+ */
+internal struct InvalidCodeBlockOption: Checker {
+    var problems = [Problem]()
+
+    /// Parsing options for code blocks
+    private let knownOptions = RenderBlockContent.CodeListing.knownOptions
+
+    private var sourceFile: URL?
+
+    /// Creates a new checker that detects documents with multiple titles.
+    ///
+    /// - Parameter sourceFile: The URL to the documentation file that the checker checks.
+    init(sourceFile: URL?) {
+        self.sourceFile = sourceFile
+    }
+
+    mutating func visitCodeBlock(_ codeBlock: CodeBlock) {
+        let info = codeBlock.language?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !info.isEmpty else { return }
+
+        let tokens = info
+            .split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespaces) }
+            .filter { !$0.isEmpty }
+
+        guard !tokens.isEmpty else { return }
+
+        for token in tokens {
+            // if the token is an exact match, we don't need to do anything
+            guard !knownOptions.contains(token) else { continue }
+
+            let matches = NearMiss.bestMatches(for: knownOptions, against: token)
+
+            if !matches.isEmpty {
+                let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Unknown option \(token.singleQuoted) in code block.")
+                let possibleSolutions = matches.map { candidate in
+                    Solution(
+                        summary: "Replace \(token.singleQuoted) with \(candidate.singleQuoted).",
+                        replacements: []
+                    )
+                }
+                problems.append(Problem(diagnostic: diagnostic, possibleSolutions: possibleSolutions))
+            }
+        }
+    }
+}

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -273,6 +273,7 @@ public class DocumentationContext {
             MissingAbstract(sourceFile: source).any(),
             NonOverviewHeadingChecker(sourceFile: source).any(),
             SeeAlsoInTopicsHeadingChecker(sourceFile: source).any(),
+            InvalidCodeBlockOption(sourceFile: source).any(),
         ])
         checker.visit(document)
         diagnosticEngine.emit(checker.problems)
@@ -2457,7 +2458,6 @@ public class DocumentationContext {
             }
         }
     }
-    
     /// A closure type getting the information about a reference in a context and returns any possible problems with it.
     public typealias ReferenceCheck = (DocumentationContext, ResolvedTopicReference) -> [Problem]
 

Sources/SwiftDocC/Infrastructure/Workspace/FeatureFlags+Info.swift

@@ -37,11 +37,20 @@ extension DocumentationBundle.Info {
             self.unknownFeatureFlags = []
         }
 
+        /// This feature flag corresponds to ``FeatureFlags/isExperimentalCodeBlockAnnotationsEnabled``.
+        public var experimentalCodeBlockAnnotations: Bool?
+
+        public init(experimentalCodeBlockAnnotations: Bool? = nil) {
+            self.experimentalCodeBlockAnnotations = experimentalCodeBlockAnnotations
+            self.unknownFeatureFlags = []
+        }
+
         /// A list of decoded feature flag keys that didn't match a known feature flag.
         public let unknownFeatureFlags: [String]
 
         enum CodingKeys: String, CodingKey, CaseIterable {
             case experimentalOverloadedSymbolPresentation = "ExperimentalOverloadedSymbolPresentation"
+            case experimentalCodeBlockAnnotations = "ExperimentalCodeBlockAnnotations"
         }
 
         struct AnyCodingKeys: CodingKey {
@@ -66,6 +75,9 @@ extension DocumentationBundle.Info {
                     switch codingKey {
                     case .experimentalOverloadedSymbolPresentation:
                         self.experimentalOverloadedSymbolPresentation = try values.decode(Bool.self, forKey: flagName)
+
+                    case .experimentalCodeBlockAnnotations:
+                        self.experimentalCodeBlockAnnotations = try values.decode(Bool.self, forKey: flagName)
                     }
                 } else {
                     unknownFeatureFlags.append(flagName.stringValue)
@@ -79,6 +91,7 @@ extension DocumentationBundle.Info {
             var container = encoder.container(keyedBy: CodingKeys.self)
 
             try container.encode(experimentalOverloadedSymbolPresentation, forKey: .experimentalOverloadedSymbolPresentation)
+            try container.encode(experimentalCodeBlockAnnotations, forKey: .experimentalCodeBlockAnnotations)
         }
     }
 }

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

@@ -124,12 +124,26 @@ public enum RenderBlockContent: Equatable {
         public var code: [String]
         /// Additional metadata for this code block.
         public var metadata: RenderContentMetadata?
+        public var copyToClipboard: Bool
+
+        public enum OptionName: String, CaseIterable {
+            case nocopy
+
+            init?(caseInsensitive raw: some StringProtocol) {
+                self.init(rawValue: raw.lowercased())
+            }
+        }
+
+        public static var knownOptions: Set<String> {
+            Set(OptionName.allCases.map(\.rawValue))
+        }
 
         /// Make a new `CodeListing` with the given data.
-        public init(syntax: String?, code: [String], metadata: RenderContentMetadata?) {
+        public init(syntax: String?, code: [String], metadata: RenderContentMetadata?, copyToClipboard: Bool = FeatureFlags.current.isExperimentalCodeBlockAnnotationsEnabled) {
             self.syntax = syntax
             self.code = code
             self.metadata = metadata
+            self.copyToClipboard = copyToClipboard
         }
     }
 
@@ -697,7 +711,7 @@ extension RenderBlockContent.Table: Codable {
 extension RenderBlockContent: Codable {
     private enum CodingKeys: CodingKey {
         case type
-        case inlineContent, content, caption, style, name, syntax, code, level, text, items, media, runtimePreview, anchor, summary, example, metadata, start
+        case inlineContent, content, caption, style, name, syntax, code, level, text, items, media, runtimePreview, anchor, summary, example, metadata, start, copyToClipboard
         case request, response
         case header, rows
         case numberOfColumns, columns
@@ -719,11 +733,13 @@ extension RenderBlockContent: Codable {
             }
             self = try .aside(.init(style: style, content: container.decode([RenderBlockContent].self, forKey: .content)))
         case .codeListing:
+            let copy = FeatureFlags.current.isExperimentalCodeBlockAnnotationsEnabled
             self = try .codeListing(.init(
                 syntax: container.decodeIfPresent(String.self, forKey: .syntax),
                 code: container.decode([String].self, forKey: .code),
-                metadata: container.decodeIfPresent(RenderContentMetadata.self, forKey: .metadata)
-            ))
+                metadata: container.decodeIfPresent(RenderContentMetadata.self, forKey: .metadata),
+                copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? copy
+                ))
         case .heading:
             self = try .heading(.init(level: container.decode(Int.self, forKey: .level), text: container.decode(String.self, forKey: .text), anchor: container.decodeIfPresent(String.self, forKey: .anchor)))
         case .orderedList:
@@ -826,6 +842,7 @@ extension RenderBlockContent: Codable {
             try container.encode(l.syntax, forKey: .syntax)
             try container.encode(l.code, forKey: .code)
             try container.encodeIfPresent(l.metadata, forKey: .metadata)
+            try container.encode(l.copyToClipboard, forKey: .copyToClipboard)
         case .heading(let h):
             try container.encode(h.level, forKey: .level)
             try container.encode(h.text, forKey: .text)

Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

@@ -47,7 +47,41 @@ struct RenderContentCompiler: MarkupVisitor {
 
     mutating func visitCodeBlock(_ codeBlock: CodeBlock) -> [any RenderContent] {
         // Default to the bundle's code listing syntax if one is not explicitly declared in the code block.
-        return [RenderBlockContent.codeListing(.init(syntax: codeBlock.language ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil))]
+
+        if FeatureFlags.current.isExperimentalCodeBlockAnnotationsEnabled {
+
+            func parseLanguageString(_ input: String?) -> (lang: String? , tokens: [RenderBlockContent.CodeListing.OptionName]) {
+                guard let input else { return (lang: nil, tokens: []) }
+                let parts = input
+                    .split(separator: ",")
+                    .map { $0.trimmingCharacters(in: .whitespaces) }
+                var lang: String? = nil
+                var options: [RenderBlockContent.CodeListing.OptionName] = []
+
+                for part in parts {
+                    if let opt = RenderBlockContent.CodeListing.OptionName(caseInsensitive: part) {
+                        options.append(opt)
+                    } else if lang == nil {
+                        lang = String(part)
+                    }
+                }
+                return (lang, options)
+            }
+
+            let options = parseLanguageString(codeBlock.language)
+
+            let listing = RenderBlockContent.CodeListing(
+                syntax: options.lang ?? bundle.info.defaultCodeListingLanguage,
+                code: codeBlock.code.splitByNewlines,
+                metadata: nil,
+                copyToClipboard: !options.tokens.contains(.nocopy)
+            )
+
+            return [RenderBlockContent.codeListing(listing)]
+
+        } else {
+            return [RenderBlockContent.codeListing(.init(syntax: codeBlock.language ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, copyToClipboard: false))]
+        }
     }
 
     mutating func visitHeading(_ heading: Heading) -> [any RenderContent] {

Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json

@@ -805,6 +805,9 @@
                     },
                     "metadata": {
                         "$ref": "#/components/schemas/RenderContentMetadata"
+                    },
+                    "copyToClipboard": {
+                        "type": "boolean"
                     }
                 }
             },

Sources/SwiftDocC/Utility/FeatureFlags.swift

@@ -13,7 +13,10 @@ public struct FeatureFlags: Codable {
     /// The current feature flags that Swift-DocC uses to conditionally enable
     /// (usually experimental) behavior in Swift-DocC.
     public static var current = FeatureFlags()
-    
+
+    /// Whether or not experimental annotation of code blocks is enabled.
+    public var isExperimentalCodeBlockAnnotationsEnabled = false
+
     /// Whether or not experimental support for device frames on images and video is enabled.
     public var isExperimentalDeviceFrameSupportEnabled = false
 

Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift

@@ -19,7 +19,7 @@ extension ConvertAction {
     public init(fromConvertCommand convert: Docc.Convert, withFallbackTemplate fallbackTemplateURL: URL? = nil) throws {
         var standardError = LogHandle.standardError
         let outOfProcessResolver: OutOfProcessReferenceResolver?
-        
+        FeatureFlags.current.isExperimentalCodeBlockAnnotationsEnabled = convert.featureFlags.enableExperimentalCodeBlockAnnotations
         FeatureFlags.current.isExperimentalDeviceFrameSupportEnabled = convert.enableExperimentalDeviceFrameSupport
         FeatureFlags.current.isExperimentalLinkHierarchySerializationEnabled = convert.enableExperimentalLinkHierarchySerialization
         FeatureFlags.current.isExperimentalOverloadedSymbolPresentationEnabled = convert.enableExperimentalOverloadedSymbolPresentation

Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift

@@ -475,7 +475,13 @@ extension Docc {
         struct FeatureFlagOptions: ParsableArguments {
             @Flag(help: "Allows for custom templates, like `header.html`.")
             var experimentalEnableCustomTemplates = false
-            
+
+            @Flag(
+                name: .customLong("enable-experimental-code-block-annotations"),
+                help: "Support annotations for code blocks."
+            )
+            var enableExperimentalCodeBlockAnnotations = false
+
             @Flag(help: .hidden)
             var enableExperimentalDeviceFrameSupport = false
 
@@ -558,6 +564,14 @@ extension Docc {
 
         }
 
+        /// A user-provided value that is true if the user enables experimental support for code block annotation.
+        ///
+        /// Defaults to false.
+        public var enableExperimentalCodeBlocAnnotations: Bool {
+            get { featureFlags.enableExperimentalCodeBlockAnnotations }
+            set { featureFlags.enableExperimentalCodeBlockAnnotations = newValue}
+        }
+
         /// A user-provided value that is true if the user enables experimental support for device frames.
         ///
         /// Defaults to false.

Tests/SwiftDocCTests/Checker/Checkers/InvalidCodeBlockOptionTests.swift

@@ -0,0 +1,108 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2025 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import XCTest
+@testable import SwiftDocC
+import Markdown
+
+class InvalidCodeBlockOptionTests: XCTestCase {
+
+    func testNoOptions() {
+        let markupSource = """
+```
+let a = 1
+```
+"""
+        let document = Document(parsing: markupSource, options: [])
+        var checker = InvalidCodeBlockOption(sourceFile: nil)
+        checker.visit(document)
+        XCTAssertTrue(checker.problems.isEmpty)
+        XCTAssertEqual(RenderBlockContent.CodeListing.knownOptions, ["nocopy"])
+    }
+
+    func testOption() {
+        let markupSource = """
+```nocopy
+let a = 1
+```
+"""
+        let document = Document(parsing: markupSource, options: [])
+        var checker = InvalidCodeBlockOption(sourceFile: nil)
+        checker.visit(document)
+        XCTAssertTrue(checker.problems.isEmpty)
+    }
+
+    func testMultipleOptionTypos() {
+        let markupSource = """
+```nocoy
+let b = 2
+```
+
+```nocoy
+let c = 3
+```
+"""
+        let document = Document(parsing: markupSource, options: [])
+        var checker = InvalidCodeBlockOption(sourceFile: URL(fileURLWithPath: #file))
+        checker.visit(document)
+        XCTAssertEqual(2, checker.problems.count)
+
+        for problem in checker.problems {
+            XCTAssertEqual("org.swift.docc.InvalidCodeBlockOption", problem.diagnostic.identifier)
+            XCTAssertEqual(problem.diagnostic.summary, "Unknown option 'nocoy' in code block.")
+            XCTAssertEqual(problem.possibleSolutions.map(\.summary), ["Replace 'nocoy' with 'nocopy'."])
+        }
+    }
+
+    func testOptionDifferentTypos() throws {
+        let markupSource = """
+```swift, nocpy
+let d = 4
+```         
+
+```unknown, nocpoy
+let e = 5
+```
+
+```nocopy
+let f = 6
+```   
+
+```ncopy
+let g = 7
+```  
+"""
+        let document = Document(parsing: markupSource, options: [])
+        var checker = InvalidCodeBlockOption(sourceFile: URL(fileURLWithPath: #file))
+        checker.visit(document)
+
+        XCTAssertEqual(3, checker.problems.count)
+
+        let summaries = checker.problems.map { $0.diagnostic.summary }
+        XCTAssertEqual(summaries, [
+            "Unknown option 'nocpy' in code block.",
+            "Unknown option 'nocpoy' in code block.",
+            "Unknown option 'ncopy' in code block.",
+        ])
+
+        for problem in checker.problems {
+            XCTAssertEqual(
+                "org.swift.docc.InvalidCodeBlockOption",
+                problem.diagnostic.identifier
+            )
+
+            XCTAssertEqual(problem.possibleSolutions.count, 1)
+            let solution = try XCTUnwrap(problem.possibleSolutions.first)
+            XCTAssert(solution.summary.hasSuffix("with 'nocopy'."))
+
+        }
+    }
+}
+