Skip to content

Conversation

DebugSteven
Copy link
Contributor

@DebugSteven DebugSteven commented Sep 2, 2025

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

  1. 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
```
  1. Confirm highlighted lines and struck-through lines have the correct styling
  2. Confirm that wrapping is styled with the configured width.
  3. Confirm the show line number option shows line numbers.
  4. Confirm these options can be combined and are styled correctly.
  5. 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:
Line highlighting, striking, wrapping, and line numbers in dark theme
Line highlighting, striking, wrapping, and line numbers in light theme

Compared to without these options:
Code example without options in dark theme

@heckj
Copy link
Member

heckj commented Sep 5, 2025

@swift-ci please test

@heckj
Copy link
Member

heckj commented Sep 5, 2025

@swift-ci please test

@DebugSteven DebugSteven changed the title Add experimental code block options: highlight, strikeout, wrap Add experimental code block options: highlight, strikeout, wrap, showLineNumbers Sep 8, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants