Add experimental code block options: highlight, strikeout, wrap, showLineNumbers #1287

DebugSteven · 2025-09-02T22:27:17Z

Summary

This PR implements new code block options for line highlighting, line striking, line wrapping, and showing line numbers. When the enable-experimental-code-block flag is enabled, authors can specify options in the code block language line to control presentation:

highlight=[1, 2, 3] — highlight the given line numbers
strikeout=[3] — strikethrough the given line numbers
wrap=80 — wrap code lines to the specified character width
showLineNumbers — turn on line numbers
These options may appear after a specified language or alone.

User Experience

With the enable-experimental-code-block flag, authors can annotate code listings with these new options using the language line.

```swift, showLineNumbers, highlight=[1, 3], strikeout=[2], wrap=80
let a = 1
deprecated() // struck out
print(a) // highlighted
```

or without a language

```highlight=[2], wrap=60
let a = 1
let b = 2
let c = 3
```

highlight and strikeout accept 1-indexed arrays
wrap takes an integer and applies soft wrapping at that width

Implementation Overview

In swift-docc, this change parses showLineNumbers, highlight=[Int], strikeout=[Int], and wrap=Int from the language line in triple-backtick code blocks, where language (optionally) should be specified as the first option when it’s included.
Adds an OptionName enum on the CodeListing struct for available options.
Updates RenderNode.spec.json to document the new CodeListing fields.
Adds Utility/ParseLanguageString.swift for parsing the language string and option arrays.
Extends the InvalidCodeBlockOption checker to identify typos in options, suggest an unknown option might be the language (when it’s not placed first), and validate array indices for highlight and strikeout are within the bounds of a code block.

Dependencies

This PR builds on top of #1273 and depends on associated changes in swift-docc-render to actually render and handle the highlight, strikeout, wrap, and showLineNumbers options. The associated swift-docc-render PR is here: swiftlang/swift-docc-render#965

Testing

Setup

Use the additional-metadata branches for swift-docc and swift-docc-render with the new highlight, strikeout, wrap and showLineNumbers changes.
Rebuild documentation using swift-docc and the feature flag enable-experimental-code-block. Serve it using a local build of swift-docc-render.

How to Test

In any code listing using ``` or by adding a code listing, add the highlight, `strikeout`, `wrap` and/or `showLineNumbers` options after the language (optionally) like this:

```swift, showLineNumbers, highlight=[1,3,4], strikeout=[2, 3], wrap=40
let a = 1
let b = 2
let c = 3
let d = 4
```

Confirm highlighted lines and struck-through lines have the correct styling
Confirm that wrapping is styled with the configured width.
Confirm the show line number option shows line numbers.
Confirm these options can be combined and are styled correctly.
Verify the above behavior with and without a language token in the language line.

Checklist

Added tests
Ran the ./bin/test script and it succeeded
Updated documentation if necessary - Updated RenderNode.spec.json, holding off on documentation for experimental features

These new options looks like the below:

Compared to without these options:

…mited by commas

…rd and other code block annotations

… on language line, tests

heckj · 2025-09-05T21:30:40Z

@swift-ci please test

heckj · 2025-09-05T23:26:42Z

@swift-ci please test

d-ronnqvist

There's a few places of either API breaking changes or API that's designed in a way where it's likely to break in the future. That needs to be addressed.

Also, I have serious concerns about the way that the new code block attributes is encoded in the Render Node specification. We don't have a process for handling breaking changes to that specification today, so that format needs to be rethought to ensure that it's flexible and extensible for the type of information we want to encode there.

d-ronnqvist · 2025-09-17T15:04:46Z

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

+        public var showLineNumbers: Bool = false
+        public var strikeout: [Int] = [Int]()
+
+        public enum OptionName: String, CaseIterable {


Considering that this looks like an enum that will get more cases over time, it shouldn't be source breaking to add new cases.

One way to do that would be to add a case like _nonFrozenEnum_useDefaultCase (for example like this) to point out to the caller that they can't exhaustively switch over the cases of this enum.

Another way to do that would be to change this to a structure that's RawRepresentable of a String and add static properties for each of the known cases. If the initializer is internal, then callers will only be able to access the known values.

d-ronnqvist · 2025-09-17T15:05:40Z

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

+        public var copyToClipboard: Bool = true
+        public var wrap: Int = 100
+        public var highlight: [Int] = [Int]()
+        public var showLineNumbers: Bool = false
+        public var strikeout: [Int] = [Int]()


This is starting to look like quite bit of configuration. Perhaps it makes sense to organize it into a single structure to separatethe annotations from the code block itself.

d-ronnqvist · 2025-09-17T15:07:55Z

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

@@ -124,12 +124,39 @@ public enum RenderBlockContent: Equatable {
        public var code: [String]
        /// Additional metadata for this code block.
        public var metadata: RenderContentMetadata?
+        public var copyToClipboard: Bool = true
+        public var wrap: Int = 100
+        public var highlight: [Int] = [Int]()


This is going to be quite limiting going forward. If we require in public API that the highlight is a list of integers then we can't represent partially highlighted lines without either:

API breaking changes

having to different arrays for different types of highlights.

Also, with this API design, each time we need to add a new type of highlight we need to add a new public property. It would be more flexible if this was represented differently (for example making the style a property of the "highlight").

d-ronnqvist · 2025-09-17T15:17:25Z

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


        /// 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, wrap: Int, highlight: [Int], strikeout: [Int], showLineNumbers: Bool) {


Like in the previous PR, this is a source breaking change because callers of the previous initializer will now have an error that they're missing parameters.

Considering that each new code block feature is going to encounter the same issue, I feel like we need to approach this differently. One example of how to do that could be to group all the new properties in a structure and pass it to the initializer. This moves the problem of API breaking changes to the structure. The structure in turn can avoid API breaking changes by only having a public initializer that takes no arguments—resulting in the default values for everything. This is how the context handles its configuration. That design then changes the caller to have to create a structure with the default values and one-by-one assign each property before passing the structure to the initializer.

d-ronnqvist · 2025-09-17T15:19:46Z

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

+                    "highlight": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer"
+                        }
+                    },
+                    "strikeout": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer"
+                        }


Similar to the API design, I have serious concerns about this scaling to either new styles of highlight style or partial highlight ranges.

Unlike the Swift API, we have no process at all for breaking changes to the Render Node specification so we need to really think this through so that the JSON format is flexible and extensible for the type of information we want to encode here.

Although this is rather technical, it might be good to discuss this in the forums to get greater visibility and to get inputs from a wider audience.

d-ronnqvist · 2025-09-17T15:20:30Z

Sources/SwiftDocC/Utility/ParseLanguageString.swift

+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+/// A function that parses array values on code block options from the language line string
+public func parseCodeBlockOptionArray(_ value: String?) -> [Int]? {


I don't think that callers have any reasons to use this, so it shouldn't be public API.

In general free functions can have a tendency to pollute the API because they're always available in every scope.

The Swift API Design Guidelines calls out "Prefer methods and properties to free functions." in its general conventions.

In this case, it might make sense to check what code needs to call these functions and move them closer to the caller, ideally making them private if there's only a single caller.

Also, this method doesn't look like its ever returning nil so it doesn't need an optional return type.

d-ronnqvist · 2025-09-17T15:20:37Z

Sources/SwiftDocC/Utility/ParseLanguageString.swift

+}
+
+/// A function that parses the language line options on code blocks, returning the language and tokens, an array of OptionName and option values
+public func tokenizeLanguageString(_ input: String?) -> (lang: String?, tokens: [(RenderBlockContent.CodeListing.OptionName, String?)]) {


Like above, I don't think that callers have any reasons to use this, so it shouldn't be public API.

DebugSteven mentioned this pull request Sep 2, 2025

Implement highlight/strikeout/wrap for code listings swiftlang/swift-docc-render#965

Open

3 tasks

Jesse Haigh added 21 commits September 5, 2025 09:27

WIP add copy button to CodeListing

e5332d3

update OpenAPI spec with copyToClipboard on CodeListing

7a096df

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

e7fb85d

…mited by commas

fix unit tests

9d3ad95

add unit test for copyToClipboard

4c27372

fixup missing async on test

4982d22

update docs

578cbee

copy by default

5652a94

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

c7ab13d

…rd and other code block annotations

add more tests, remove docs, code cleanup

a429323

WIP diagnostics

25a3cf6

WIP diagnostics: tests

dde7455

add code block options onto RenderBlockContent.CodeListing

0a28b07

WIP wrap and highlight

b8f2a40

fix tests

7df029c

WIP tests, WIP parsing for wrap and highlight

86fd210

change parsing to handle values after = and arrays

96c6069

add strikeout option

644f28c

parse strikeout option, solution for language not as the first option…

033b3b9

… on language line, tests

validate array values in code block options for highlight and strikeout

8cd9c23

showLineNumbers option

fbe197e

DebugSteven force-pushed the additional-metadata branch from e2c790d to fbe197e Compare September 5, 2025 19:53

remove trailing comma

b49c6e2

DebugSteven changed the title ~~Add experimental code block options: highlight, strikeout, wrap~~ Add experimental code block options: highlight, strikeout, wrap, showLineNumbers Sep 8, 2025

test showLineNumbers

ec3f677

d-ronnqvist requested changes Sep 17, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add experimental code block options: highlight, strikeout, wrap, showLineNumbers #1287

Add experimental code block options: highlight, strikeout, wrap, showLineNumbers #1287

DebugSteven commented Sep 2, 2025 •

edited

Loading

Uh oh!

heckj commented Sep 5, 2025

Uh oh!

heckj commented Sep 5, 2025

Uh oh!

d-ronnqvist left a comment

Uh oh!

d-ronnqvist Sep 17, 2025

Uh oh!

d-ronnqvist Sep 17, 2025

Uh oh!

d-ronnqvist Sep 17, 2025

Uh oh!

d-ronnqvist Sep 17, 2025

Uh oh!

d-ronnqvist Sep 17, 2025

Uh oh!

d-ronnqvist Sep 17, 2025 •

edited

Loading

Uh oh!

d-ronnqvist Sep 17, 2025

Uh oh!

d-ronnqvist Sep 17, 2025

Uh oh!

d-ronnqvist Sep 17, 2025

Uh oh!

d-ronnqvist Sep 17, 2025

Uh oh!

d-ronnqvist Sep 17, 2025

Uh oh!

Uh oh!

Add experimental code block options: highlight, strikeout, wrap, showLineNumbers #1287

Are you sure you want to change the base?

Add experimental code block options: highlight, strikeout, wrap, showLineNumbers #1287

Conversation

DebugSteven commented Sep 2, 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 Sep 5, 2025

Uh oh!

heckj commented Sep 5, 2025

Uh oh!

d-ronnqvist 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!

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!

d-ronnqvist Sep 17, 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!

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!

DebugSteven commented Sep 2, 2025 •

edited

Loading

d-ronnqvist Sep 17, 2025 •

edited

Loading