Implement highlight/strikeout/wrap for code listings

[DebugSteven]

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-annotations flag is enabled, code listings will have access to highlight, strikeout, and wrap properties forwarded in the render JSON.

User Experience

• Lines listed in highlight appear with the same highlight seen in tutorials.
• Lines listed in strikeout appear with a strikethrough line.
• When wrap is present and greater than 0, code lines are soft-wrapped near the specified width.
• When the showLineNumbers option is used on a code block, line numbers will render.
• These options can be combined in the same code block.

Implementation Overview

• Reads highlight: [Int]?, strikeout: [Int]?, wrap: Int?, and showLineNumbers (boolean) from RenderBlockContent.codeListing
• Applies highlighting and strikethrough per line
• Applies wrapping and line layout to the specified width per code block container

Dependencies

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

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-annotations. 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, highlight=[1,3,4], strikeout=[2, 3], wrap=40
let a = 1
let b = 2
let c = 3
let d = 4
```

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

Checklist

• Added tests
• Ran npm test, and it succeeded
• Updated documentation if necessary

These new options looks like the below:

Compared to without these options:

[mportiz08]

I haven't had a chance to check out the code in this PR yet, but I have a quick question about the styling for highlighted lines:

Would it maybe make sense to try and re-use the highlight color/style that are already used in tutorials? Example:

Or maybe you've already tried that already. The fluorescent orange color brings warning/deprecation semantics to my mind, which doesn't necessarily seem like the same idea.

[mportiz08]

I'm also curious if you've considered adding the ability to configure line number display on/off with a custom setting like this?

I feel like it would be super useful in combination with the new wrapping feature to more easily distinguish between soft wrapped line vs purposeful newlines in the actual code.

[marinaaisa]

Hi @DebugSteven , amazing work! thank you so much for your PR!

I left some suggestions to refactor the code a bit but everything else is great!

As @mportiz08 mentioned, I also think that you should consider changing the code of the highlighting to match the tutorials ones :)

Excited for this PR!

[heckj]

@marinaaisa @mportiz08 I was the source for the different coloration - I wanted an option that was significantly more like a highlighter so that it would pull more attention, especially in a an article context where a reader is more likely to be skimming, so that it drew their attention to the relevant sections quickly.

I totally get wanting to keep it consistent though, my biggest concern, especially with the dark mode viewing, is that the highlighting is too subtle - and only if you're really focused on the content will you capture that detail.

We also wanted to extend beyond what the tutorial offers - for example, the tutorial content doesn't display a deleted line, which is sometimes a critical piece of what's happening in an explanation, hence reaching for the strikeout flavoring.

[DebugSteven]

I got some feedback on the forums that people would like to see a way to highlight errors. David showed some examples where people indicate errors using plain text comments. Would it be acceptable to add an additional option for error highlighting with that orange color? Would you like error highlighting to have the same opacity as the highlighting for lines and in tutorials?

[mportiz08]

The code looks pretty good to me so far right now—no obvious issues I'm noticing. I know that there is still some ongoing discussion on the syntax and JSON changes in the forums, but I think this PR is in good shape depending on how that discussion goes.

My only concern about the example screenshots is the one where content gets soft wrapped and the wrapped content starts at the very left edge of the container whereas I might expect it to start after the vertical space that is being used for the line numbers—pretty minor concern though and possibly could be addressed in the future (guessing it might be tricky to get it right).

Also, you may need to update the tests after merging in the latest main—we recently updated the testing library dependency which has some minor changes to the APIs for things like find, etc

[mportiz08]

I got some feedback on the forums that people would like to see a way to highlight errors. David showed some examples where people indicate errors using plain text comments. Would it be acceptable to add an additional option for error highlighting with that orange color? Would you like error highlighting to have the same opacity as the highlighting for lines and in tutorials?

I don't have very strong opinions on this, but it looks like the highlight styling is already utilizing a CSS property for the color of the highlight, so hopefully this is something that can be easily extended for situations like that if we want to support it.

[d-ronnqvist]

I got some feedback on the forums that people would like to see a way to highlight errors. David showed some examples where people indicate errors using plain text comments. Would it be acceptable to add an additional option for error highlighting with that orange color? Would you like error highlighting to have the same opacity as the highlighting for lines and in tutorials?

I don't have very strong opinions on this, but it looks like the highlight styling is already utilizing a CSS property for the color of the highlight, so hopefully this is something that can be easily extended for situations like that if we want to support it.

I don't necessarily suggest that we implement error highlighting right now but I want us to think about how this feature would be able to grow to support those kinds of highlights.

[heckj]

@swift-ci please test

[heckj]

@swift-ci please test

[QuietMisdreavus]

@swift-ci Please test

[mportiz08]

Awesome work! I think DocC users will love having these new capabilities :)

One minor visual thing I noticed is that the highlights can look a little less than ideal when the line numbers aren't enabled. (Looks great with line numbers enabled though!)

There isn't any spacing between the highlight edges and the content and the alignment between highlighted/non-highlighted lines is slightly off.

[heckj]

@swift-ci please test

[mportiz08]

This seems to be adding spacing for normal, unnumbered code listings without any of the new styles applied.

I think you added this to account for the issue I found with aligning highlighted/non-highlighted lines. Is there a small tweak we can do to this so that this extra spacing is only added in that scenario?

[DebugSteven]

You're right, that is why I added it. I was having a difficult time figuring out a way to get the spacing and alignment looking right. I'm not sure if this was a reasonable way to approach it.

If it is though, could I add an additional :has(.highlighted), so it would be .code-listing:not(:has(.code-number)):has(.highlighted)? That way the padding would apply to only code listings with highlighted lines in it.

Otherwise, do you have a different suggestion you'd prefer? I'm happy to investigate another approach.

[mportiz08]

There might be a more efficient selector for this, but in general I think that's fine—as long as it correctly only applies the special padding when it is necessary. We can always try to improve the selector after once we get it working.

Thanks for looking into this—I feel like spacing in the code listings has always been especially tricky.

[DebugSteven]

Thank you. I've pushed up that change.

I verified the selector only applies when it should (highlighted lines, no line numbers, and with/out other options). Locally, I added a red outline for testing to make it obvious to me and confirmed it didn't appear for other cases (strikeout/wrap) or when showLineNumbers is on.

.code-listing:not(:has(.code-number)):has(.highlighted) .code-line-container {
  padding-left: $code-number-padding-left;
  outline: 2px solid red; // for local testing
}

Screenshot below uses:

```shell, highlight=[1,2,3]
docc convert MyNewPackage.docc \
  --fallback-display-name MyNewPackage \
  --fallback-bundle-identifier com.example.MyNewPackage \
  --fallback-bundle-version 1 \
  --additional-symbol-graph-dir .build \
  --output-dir MyNewPackage.doccarchive
```

[mportiz08]

Awesome, I think we're super close now!

Sorry for being so tedious and detailed about this, but I'm noticing that there's still a slight difference in the left-hand spacing for code listings in the following 2 scenarios:

• main
• this branch with no experimental flag (has slightly more spacing compared to main even with this feature turned off)

The issue I found with the highlighted/non-highlighted alignment looks good now though! I think there just might be an additional spacing other than the padding now that needs to be conditionalized—possibly a transparent border that might also have been meant for numbered code listings or something.

[heckj]

@swift-ci please test