diff --git a/Sources/SwiftDocC/Checker/Checkers/InvalidCodeBlockOption.swift b/Sources/SwiftDocC/Checker/Checkers/InvalidCodeBlockOption.swift
index ca8bd2cb5..e483fa76c 100644
--- a/Sources/SwiftDocC/Checker/Checkers/InvalidCodeBlockOption.swift
+++ b/Sources/SwiftDocC/Checker/Checkers/InvalidCodeBlockOption.swift
@@ -19,7 +19,7 @@ internal struct InvalidCodeBlockOption: Checker {
     var problems = [Problem]()
 
     /// Parsing options for code blocks
-    private let knownOptions = RenderBlockContent.CodeListing.knownOptions
+    private let knownOptions = RenderBlockContent.CodeBlockOptions.knownOptions
 
     private var sourceFile: URL?
 
@@ -31,32 +31,67 @@ internal struct InvalidCodeBlockOption: Checker {
     }
 
     mutating func visitCodeBlock(_ codeBlock: CodeBlock) {
-        let info = codeBlock.language?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        guard !info.isEmpty else { return }
+        let (lang, tokens) = RenderBlockContent.CodeBlockOptions.tokenizeLanguageString(codeBlock.language)
 
-        let tokens = info
-            .split(separator: ",")
-            .map { $0.trimmingCharacters(in: .whitespaces) }
-            .filter { !$0.isEmpty }
+        func matches(token: RenderBlockContent.CodeBlockOptions.OptionName, value: String?) {
+            guard token == .unknown, let value = value else { return }
 
-        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)
+            let matches = NearMiss.bestMatches(for: knownOptions, against: value)
 
             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 diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Unknown option \(value.singleQuoted) in code block.")
                 let possibleSolutions = matches.map { candidate in
                     Solution(
-                        summary: "Replace \(token.singleQuoted) with \(candidate.singleQuoted).",
+                        summary: "Replace \(value.singleQuoted) with \(candidate.singleQuoted).",
                         replacements: []
                     )
                 }
                 problems.append(Problem(diagnostic: diagnostic, possibleSolutions: possibleSolutions))
+            } else if lang == nil {
+                let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Unknown option \(value.singleQuoted) in code block.")
+                let possibleSolutions =
+                Solution(
+                    summary: "If \(value.singleQuoted) is the language for this code block, then write \(value.singleQuoted) as the first option.",
+                    replacements: []
+                )
+                problems.append(Problem(diagnostic: diagnostic, possibleSolutions: [possibleSolutions]))
+            }
+        }
+
+        func validateArrayIndices(token: RenderBlockContent.CodeBlockOptions.OptionName, value: String?) {
+            guard token == .highlight || token == .strikeout, let value = value else { return }
+            // code property ends in a newline. this gives us a bogus extra line.
+            let lineCount: Int = codeBlock.code.split(omittingEmptySubsequences: false, whereSeparator: { $0.isNewline }).count - 1
+
+            let indices = RenderBlockContent.CodeBlockOptions.parseCodeBlockOptionsArray(value)
+
+            if !value.isEmpty, indices.isEmpty {
+                let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Could not parse \(token.rawValue.singleQuoted) indices from \(value.singleQuoted). Expected an integer (e.g. 3) or an array (e.g. [1, 3, 5])")
+                problems.append(Problem(diagnostic: diagnostic, possibleSolutions: []))
+                return
             }
+
+            let invalid = indices.filter { $0 < 1 || $0 > lineCount }
+            guard !invalid.isEmpty else { return }
+
+            let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Invalid \(token.rawValue.singleQuoted) index\(invalid.count == 1 ? "" : "es") in \(value.singleQuoted) for a code block with \(lineCount) line\(lineCount == 1 ? "" : "s"). Valid range is 1...\(lineCount).")
+            let solutions: [Solution] = {
+                if invalid.contains(where: {$0 == lineCount + 1}) {
+                    return [Solution(
+                        summary: "If you intended the last line, change '\(lineCount + 1)' to \(lineCount).",
+                        replacements: []
+                    )]
+                }
+                return []
+            }()
+            problems.append(Problem(diagnostic: diagnostic, possibleSolutions: solutions))
+        }
+
+        for (token, value) in tokens {
+            matches(token: token, value: value)
+            validateArrayIndices(token: token, value: value)
         }
+        // check if first token (lang) might be a typo
+        matches(token: .unknown, value: lang)
     }
 }
diff --git a/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift b/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift
index 85ac03182..2b74a95e3 100644
--- a/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift
+++ b/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift
@@ -124,10 +124,60 @@ public enum RenderBlockContent: Equatable {
         public var code: [String]
         /// Additional metadata for this code block.
         public var metadata: RenderContentMetadata?
+        /// Annotations for code blocks
+        public var options: CodeBlockOptions?
+
+        /// Make a new `CodeListing` with the given data.
+        public init(syntax: String?, code: [String], metadata: RenderContentMetadata?, options: CodeBlockOptions?) {
+            self.syntax = syntax
+            self.code = code
+            self.metadata = metadata
+            self.options = options
+        }
+    }
+
+    public struct CodeBlockOptions: Equatable {
+        public var language: String?
         public var copyToClipboard: Bool
+        public var showLineNumbers: Bool
+        public var wrap: Int
+        public var lineAnnotations: [LineAnnotation]
+
+        public struct Position: Equatable, Comparable, Codable {
+            public static func < (lhs: RenderBlockContent.CodeBlockOptions.Position, rhs: RenderBlockContent.CodeBlockOptions.Position) -> Bool {
+                if lhs.line == rhs.line, let lhsCharacter = lhs.character, let rhsCharacter = rhs.character {
+                    return lhsCharacter < rhsCharacter
+                }
+                return lhs.line < rhs.line
+            }
+
+            public init(line: Int, character: Int? = nil) {
+                self.line = line
+                self.character = character
+            }
+
+            public var line: Int
+            public var character: Int?
+        }
+
+        public struct LineAnnotation: Equatable, Codable {
+            public var style: String
+            public var range: Range<Position>
+            
+            public init(style: String, range: Range<Position>) {
+                self.style = style
+                self.range = range
+            }
+        }
 
         public enum OptionName: String, CaseIterable {
+            case _nonFrozenEnum_useDefaultCase
             case nocopy
+            case wrap
+            case highlight
+            case showLineNumbers
+            case strikeout
+            case unknown
 
             init?(caseInsensitive raw: some StringProtocol) {
                 self.init(rawValue: raw.lowercased())
@@ -138,12 +188,165 @@ public enum RenderBlockContent: Equatable {
             Set(OptionName.allCases.map(\.rawValue))
         }
 
-        /// Make a new `CodeListing` with the given data.
-        public init(syntax: String?, code: [String], metadata: RenderContentMetadata?, copyToClipboard: Bool = FeatureFlags.current.isExperimentalCodeBlockAnnotationsEnabled) {
-            self.syntax = syntax
-            self.code = code
-            self.metadata = metadata
+        // empty initializer with default values
+        public init() {
+            self.language = ""
+            self.copyToClipboard = FeatureFlags.current.isExperimentalCodeBlockAnnotationsEnabled
+            self.showLineNumbers = false
+            self.wrap = 0
+            self.lineAnnotations = []
+        }
+
+        public init(parsingLanguageString language: String?) {
+            let (lang, tokens) = Self.tokenizeLanguageString(language)
+
+            self.language = lang
+            self.copyToClipboard = !tokens.contains { $0.name == .nocopy }
+            self.showLineNumbers = tokens.contains { $0.name == .showLineNumbers }
+
+            if let wrapString = tokens.first(where: { $0.name == .wrap })?.value,
+               let wrapValue = Int(wrapString) {
+                self.wrap = wrapValue
+            } else {
+                self.wrap = 0
+            }
+
+            var annotations: [LineAnnotation] = []
+
+            if let highlightString = tokens.first(where: { $0.name == .highlight })?.value {
+                let highlightValue = Self.parseCodeBlockOptionsArray(highlightString)
+                for line in highlightValue {
+                    let pos = Position(line: line, character: nil)
+                    let range = pos..<pos
+                    annotations.append(LineAnnotation(style: "highlight", range: range))
+                }
+            }
+
+            if let strikeoutString = tokens.first(where: { $0.name == .strikeout })?.value {
+                let strikeoutValue = Self.parseCodeBlockOptionsArray(strikeoutString)
+                for line in strikeoutValue {
+                    let pos = Position(line: line, character: nil)
+                    let range = pos..<pos
+                    annotations.append(LineAnnotation(style: "strikeout", range: range))
+                }
+            }
+
+            self.lineAnnotations = annotations
+        }
+
+        public init(copyToClipboard: Bool = FeatureFlags.current.isExperimentalCodeBlockAnnotationsEnabled, showLineNumbers: Bool = false, wrap: Int, highlight: [Int], strikeout: [Int]) {
+            self.copyToClipboard = copyToClipboard
+            self.showLineNumbers = showLineNumbers
+            self.wrap = wrap
+
+            var annotations: [LineAnnotation] = []
+            for line in highlight {
+                    let pos = Position(line: line, character: nil)
+                    let range = pos..<pos
+                    annotations.append(LineAnnotation(style: "highlight", range: range))
+            }
+            for line in strikeout {
+                    let pos = Position(line: line, character: nil)
+                    let range = pos..<pos
+                    annotations.append(LineAnnotation(style: "strikeout", range: range))
+            }
+            self.lineAnnotations = annotations
+        }
+
+        public init(copyToClipboard: Bool, showLineNumbers: Bool, wrap: Int, lineAnnotations: [LineAnnotation]) {
             self.copyToClipboard = copyToClipboard
+            self.showLineNumbers = showLineNumbers
+            self.wrap = wrap
+            self.lineAnnotations = lineAnnotations
+        }
+
+        /// A function that parses array values on code block options from the language line string
+        static internal func parseCodeBlockOptionsArray(_ value: String?) -> [Int] {
+            guard var s = value?.trimmingCharacters(in: .whitespaces), !s.isEmpty else { return [] }
+
+            if s.hasPrefix("[") && s.hasSuffix("]") {
+                s.removeFirst()
+                s.removeLast()
+            }
+
+            return s.split(separator: ",").compactMap { Int($0.trimmingCharacters(in: .whitespaces)) }
+        }
+
+        /// A function that parses the language line options on code blocks, returning the language and tokens, an array of OptionName and option values
+        static internal func tokenizeLanguageString(_ input: String?) -> (lang: String?, tokens: [(name: OptionName, value: String?)]) {
+            guard let input else { return (lang: nil, tokens: []) }
+
+            let parts = parseLanguageString(input)
+            var tokens: [(OptionName, String?)] = []
+            var lang: String? = nil
+
+            for (index, part) in parts.enumerated() {
+                if let eq = part.firstIndex(of: "=") {
+                    let key = part[..<eq].trimmingCharacters(in: .whitespaces).lowercased()
+                    let value = part[part.index(after: eq)...].trimmingCharacters(in: .whitespaces)
+                    if key == "wrap" {
+                        tokens.append((.wrap, value))
+                    } else if key == "highlight" {
+                        tokens.append((.highlight, value))
+                    } else if key == "strikeout" {
+                        tokens.append((.strikeout, value))
+                    } else {
+                        tokens.append((.unknown, key))
+                    }
+                } else {
+                    let key = part.trimmingCharacters(in: .whitespaces).lowercased()
+                    if key == "nocopy" {
+                        tokens.append((.nocopy, nil as String?))
+                    } else if key == "showlinenumbers" {
+                        tokens.append((.showLineNumbers, nil as String?))
+                    } else if key == "wrap" {
+                        tokens.append((.wrap, nil as String?))
+                    } else if key == "highlight" {
+                        tokens.append((.highlight, nil as String?))
+                    } else if key == "strikeout" {
+                        tokens.append((.strikeout, nil as String?))
+                    } else if index == 0 && !key.contains("[") && !key.contains("]") {
+                        lang = key
+                    } else {
+                        tokens.append((.unknown, key))
+                    }
+                }
+            }
+            return (lang, tokens)
+        }
+
+        // helper function for tokenizeLanguageString to parse the language line
+        static func parseLanguageString(_ input: String?) -> [Substring] {
+
+            guard let input else { return [] }
+            var parts: [Substring] = []
+            var start = input.startIndex
+            var i = input.startIndex
+
+            var bracketDepth = 0
+
+            while i < input.endIndex {
+                let c = input[i]
+
+                if c == "[" { bracketDepth += 1 }
+                else if c == "]" { bracketDepth = max(0, bracketDepth - 1) }
+                else if c == "," && bracketDepth == 0 {
+                    let seq = input[start..<i]
+                    if !seq.isEmpty {
+                        parts.append(seq)
+                    }
+                    input.formIndex(after: &i)
+                    start = i
+                    continue
+                }
+                input.formIndex(after: &i)
+            }
+            let tail = input[start..<input.endIndex]
+            if !tail.isEmpty {
+                parts.append(tail)
+            }
+
+            return parts
         }
     }
 
@@ -711,7 +914,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, copyToClipboard
+        case inlineContent, content, caption, style, name, syntax, code, level, text, items, media, runtimePreview, anchor, summary, example, metadata, start, copyToClipboard, showLineNumbers, wrap, lineAnnotations
         case request, response
         case header, rows
         case numberOfColumns, columns
@@ -734,12 +937,23 @@ extension RenderBlockContent: Codable {
             self = try .aside(.init(style: style, content: container.decode([RenderBlockContent].self, forKey: .content)))
         case .codeListing:
             let copy = FeatureFlags.current.isExperimentalCodeBlockAnnotationsEnabled
+            let options: CodeBlockOptions?
+            if !Set(container.allKeys).isDisjoint(with: [.copyToClipboard, .showLineNumbers, .wrap, .lineAnnotations]) {
+                options = try CodeBlockOptions(
+                    copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? copy,
+                    showLineNumbers: container.decodeIfPresent(Bool.self, forKey: .showLineNumbers) ?? false,
+                    wrap: container.decodeIfPresent(Int.self, forKey: .wrap) ?? 0,
+                    lineAnnotations: container.decodeIfPresent([CodeBlockOptions.LineAnnotation].self, forKey: .lineAnnotations) ?? []
+                )
+            } else {
+                options = nil
+            }
             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),
-                copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? copy
-                ))
+                options: options
+            ))
         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:
@@ -842,7 +1056,10 @@ 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)
+            try container.encodeIfPresent(l.options?.copyToClipboard, forKey: .copyToClipboard)
+            try container.encodeIfPresent(l.options?.showLineNumbers, forKey: .showLineNumbers)
+            try container.encodeIfPresent(l.options?.wrap, forKey: .wrap)
+            try container.encodeIfPresent(l.options?.lineAnnotations, forKey: .lineAnnotations)
         case .heading(let h):
             try container.encode(h.level, forKey: .level)
             try container.encode(h.text, forKey: .text)
diff --git a/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift b/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift
index e79e6fdfc..8c72c6436 100644
--- a/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift
+++ b/Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift
@@ -49,38 +49,18 @@ struct RenderContentCompiler: MarkupVisitor {
         // Default to the bundle's code listing syntax if one is not explicitly declared in the code block.
 
         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 codeBlockOptions = RenderBlockContent.CodeBlockOptions(parsingLanguageString: codeBlock.language)
             let listing = RenderBlockContent.CodeListing(
-                syntax: options.lang ?? bundle.info.defaultCodeListingLanguage,
+                syntax: codeBlockOptions.language ?? bundle.info.defaultCodeListingLanguage,
                 code: codeBlock.code.splitByNewlines,
                 metadata: nil,
-                copyToClipboard: !options.tokens.contains(.nocopy)
+                options: codeBlockOptions
             )
 
             return [RenderBlockContent.codeListing(listing)]
 
         } else {
-            return [RenderBlockContent.codeListing(.init(syntax: codeBlock.language ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, copyToClipboard: false))]
+            return [RenderBlockContent.codeListing(.init(syntax: codeBlock.language ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, options: nil))]
         }
     }
     
diff --git a/Sources/SwiftDocC/Semantics/Snippets/Snippet.swift b/Sources/SwiftDocC/Semantics/Snippets/Snippet.swift
index 5dc54c091..a6f7f34db 100644
--- a/Sources/SwiftDocC/Semantics/Snippets/Snippet.swift
+++ b/Sources/SwiftDocC/Semantics/Snippets/Snippet.swift
@@ -92,11 +92,14 @@ extension Snippet: RenderableDirectiveConvertible {
                 .linesWithoutLeadingWhitespace()
                 // Make dedicated copies of each line because the RenderBlockContent.codeListing requires it.
                 .map { String($0) }
+
+            let options = RenderBlockContent.CodeBlockOptions()
             
-            return [RenderBlockContent.codeListing(.init(syntax: mixin.language, code: lines, metadata: nil))]
+            return [RenderBlockContent.codeListing(.init(syntax: mixin.language, code: lines, metadata: nil, options: options))]
         } else {
             // Render the full snippet and its explanatory content.
-            let fullCode = RenderBlockContent.codeListing(.init(syntax: mixin.language, code: mixin.lines, metadata: nil))
+            let options = RenderBlockContent.CodeBlockOptions()
+            let fullCode = RenderBlockContent.codeListing(.init(syntax: mixin.language, code: mixin.lines, metadata: nil, options: options))
             
             var content: [any RenderContent] = resolvedSnippet.explanation?.children.flatMap { contentCompiler.visit($0) } ?? []
             content.append(fullCode)
diff --git a/Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json b/Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json
index 628a2d98f..4f25303ac 100644
--- a/Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json
+++ b/Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json
@@ -781,6 +781,39 @@
                     }
                 }
             },
+            "LineAnnotation": {
+                "type": "object",
+                "properties": {
+                    "style": {
+                        "type": "string",
+                        "enum": ["highlight", "strikeout"]
+                    },
+                    "range": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/Position"
+                        }
+                    }
+                },
+                "required": [
+                    "style",
+                    "range"
+                ]
+            },
+            "Position": {
+                "type": "object",
+                "properties": {
+                    "line": {
+                        "type": "integer"
+                    },
+                    "character": {
+                        "type": "integer"
+                    }
+                },
+                "required": [
+                    "line"
+                ]
+            },
             "CodeListing": {
                 "type": "object",
                 "required": [
@@ -808,6 +841,18 @@
                     },
                     "copyToClipboard": {
                         "type": "boolean"
+                    },
+                    "showLineNumbers": {
+                        "type": "boolean"
+                    },
+                    "wrap": {
+                        "type": "integer"
+                    },
+                    "lineAnnotations": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/LineAnnotation"
+                        }
                     }
                 }
             },
diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
index c23c8c55b..4d7272d3a 100644
--- a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
+++ b/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.isExperimentalCodeBlockAnnotationsEnabled = convert.enableExperimentalCodeBlockAnnotations
         FeatureFlags.current.isExperimentalDeviceFrameSupportEnabled = convert.enableExperimentalDeviceFrameSupport
         FeatureFlags.current.isExperimentalLinkHierarchySerializationEnabled = convert.enableExperimentalLinkHierarchySerialization
         FeatureFlags.current.isExperimentalOverloadedSymbolPresentationEnabled = convert.enableExperimentalOverloadedSymbolPresentation
diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift
index aa427bdb1..a33715a62 100644
--- a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift
+++ b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift
@@ -567,7 +567,7 @@ 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 {
+        public var enableExperimentalCodeBlockAnnotations: Bool {
             get { featureFlags.enableExperimentalCodeBlockAnnotations }
             set { featureFlags.enableExperimentalCodeBlockAnnotations = newValue}
         }
diff --git a/Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md b/Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md
index 07d44ee0c..9793f9717 100644
--- a/Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md
+++ b/Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md
@@ -4,35 +4,35 @@ Enhance your content's presentation with special formatting and styling for text
 
 ## Overview
 
-Use [Markdown](https://daringfireball.net/projects/markdown/syntax), a 
-lightweight markup language, to give structure and style to your documentation. 
-DocC includes a custom dialect of Markdown, documentation markup, which 
-extends Markdown's syntax to include features like symbol linking, improved 
+Use [Markdown](https://daringfireball.net/projects/markdown/syntax), a
+lightweight markup language, to give structure and style to your documentation.
+DocC includes a custom dialect of Markdown, documentation markup, which
+extends Markdown's syntax to include features like symbol linking, improved
 image support, term lists, and asides.
 
-To ensure consistent structure and styling, use DocC's documentation markup for 
+To ensure consistent structure and styling, use DocC's documentation markup for
 all of the documentation you write.
 
 ### Add a Page Title and Section Headers
 
-To add a page title, precede the text you want to use with a hash (`#`) and a 
+To add a page title, precede the text you want to use with a hash (`#`) and a
 space. For the page title of an article or API collection, use plain text only.
 
 ```markdown
 # Getting Started with Sloths
 ```
 
-> Important: Page titles must be the first line of content in a documentation 
+> Important: Page titles must be the first line of content in a documentation
 file. One or more empty lines can precede the page title.
 
-For the page title of a landing page, enter a symbol link by wrapping the framework's 
+For the page title of a landing page, enter a symbol link by wrapping the framework's
 module name within a set of double backticks (\`\`).
 
 ```markdown
 # ``SlothCreator``
 ```
 
-For a documentation extension file, enter a symbol link by wrapping the path to the symbol 
+For a documentation extension file, enter a symbol link by wrapping the path to the symbol
 within double backticks (\`\`). The path may start with the framework's module name
 or with the name of a top-level symbol in the module.
 
@@ -48,41 +48,41 @@ The following example shows a documentation extension link to the same symbol st
 # ``CareSchedule/Event``
 ```
 
-Augment every page title with a short and concise single-sentence abstract or 
-summary that provides additional information about the content. Add the summary 
+Augment every page title with a short and concise single-sentence abstract or
+summary that provides additional information about the content. Add the summary
 using a new paragraph directly below the page title.
 
 ```markdown
 # Getting Started with Sloths
 
 Create a sloth and assign personality traits and abilities.
-```  
+```
 
-To add a header for an Overview or a Discussion section, use a double hash 
+To add a header for an Overview or a Discussion section, use a double hash
 (`##`) and a space, and then include either term in plain text.
 
 ```markdown
 ## Overview
 ```
 
-For all other section headers, use a triple hash (`###`) and a space, and then 
+For all other section headers, use a triple hash (`###`) and a space, and then
 add the title of the header in plain text.
 
 ```markdown
 ### Create a Sloth
 ```
 
-Use this type of section header in framework landing pages, top-level pages, 
-articles, and occasionally in symbol reference pages where you need to 
+Use this type of section header in framework landing pages, top-level pages,
+articles, and occasionally in symbol reference pages where you need to
 provide more detail.
 
 ### Format Text in Bold, Italics, and Code Voice
 
-DocC provides three ways to format the text in your documentation. You can 
-apply bold or italic styling, or you can use code voice, which renders the 
+DocC provides three ways to format the text in your documentation. You can
+apply bold or italic styling, or you can use code voice, which renders the
 specified text in a monospace font.
 
-To add bold styling, wrap the text in a pair of double asterisks (`**`). 
+To add bold styling, wrap the text in a pair of double asterisks (`**`).
 Alternatively, use double underscores (`__`).
 
 The following example uses bold styling for the names of the sloths:
@@ -92,42 +92,42 @@ The following example uses bold styling for the names of the sloths:
 __Silly Sloth__: Prefers twigs for breakfast.
 ```
 
-Use italicized text to introduce new or alternative terms to the reader. To add 
-italic styling, wrap the text in a set of single underscores (`_`) or single 
+Use italicized text to introduce new or alternative terms to the reader. To add
+italic styling, wrap the text in a set of single underscores (`_`) or single
 asterisks (`*`).
 
-The following example uses italics for the words _metabolism_ and _habitat_: 
+The following example uses italics for the words _metabolism_ and _habitat_:
 
 ```markdown
 A sloth's _metabolism_ is highly dependent on its *habitat*.
 ```
 
-Use code voice to refer to symbols inline, or to include short code fragments, 
-such as class names or method signatures.  To add code voice, wrap the text in 
+Use code voice to refer to symbols inline, or to include short code fragments,
+such as class names or method signatures.  To add code voice, wrap the text in
 a set of backticks (\`).
 
-In the following example, DocC renders the words _ice_, _fire_, _wind_, and 
+In the following example, DocC renders the words _ice_, _fire_, _wind_, and
 _lightning_ in a monospace font:
 
 ```markdown
-If your sloth possesses one of the special powers: `ice`, `fire`, 
+If your sloth possesses one of the special powers: `ice`, `fire`,
 `wind`, or `lightning`.
 ```
 
-> Note: To include multiple lines of code, use a code listing instead. For more 
+> Note: To include multiple lines of code, use a code listing instead. For more
 information, see <doc:formatting-your-documentation-content#Add-Code-Listings>.
 
 ### Add Code Listings
 
-DocC includes support for code listings, or fenced code blocks, which allow you 
-to go beyond the basic declaration sections you find in symbol reference pages, 
-and to provide more complete code examples for adopters of your framework. You can 
-include code listings in your in-source symbol documentation, in extension 
+DocC includes support for code listings, or fenced code blocks, which allow you
+to go beyond the basic declaration sections you find in symbol reference pages,
+and to provide more complete code examples for adopters of your framework. You can
+include code listings in your in-source symbol documentation, in extension
 files, and in articles and tutorials.
 
-To create a code listing, start a new paragraph and add three backticks 
-(\`\`\`). Then, directly following the backticks, add the name of the 
-programming language in lowercase text. Add one or more lines of code, and then 
+To create a code listing, start a new paragraph and add three backticks
+(\`\`\`). Then, directly following the backticks, add the name of the
+programming language in lowercase text. Add one or more lines of code, and then
 add a new line and terminate the code listing by adding another three backticks:
 
     ```swift
@@ -139,11 +139,11 @@ add a new line and terminate the code listing by adding another three backticks:
     }
     ```
 
-> Important: When formatting your code listing, use spaces to indent lines 
-instead of tabs so that DocC preserves the indentation when compiling your 
+> Important: When formatting your code listing, use spaces to indent lines
+instead of tabs so that DocC preserves the indentation when compiling your
 documentation.
 
-DocC uses the programming language you specify to apply the correct syntax 
+DocC uses the programming language you specify to apply the correct syntax
 color formatting. For the example above, DocC generates the following:
 
 ```swift
@@ -191,12 +191,12 @@ DocC supports the following list types:
 | ------------- | ------------------------------------------------------ |
 | Bulleted list | Groups items that can appear in any order.             |
 | Numbered list | Delineates a sequence of events in a particular order. |
-| Term list     | Defines a series of term-definition pairs.             | 
+| Term list     | Defines a series of term-definition pairs.             |
 
-> Important: Don't add images or code listings between list items. Bulleted and 
+> Important: Don't add images or code listings between list items. Bulleted and
 numbered lists must contain two or more items.
 
-To create a bulleted list, precede each of the list's items with an asterisk (`*`) and a 
+To create a bulleted list, precede each of the list's items with an asterisk (`*`) and a
 space. Alternatively, use a dash (`-`) or a plus sign (`+`) instead of an asterisk (`*`); the list markers are interchangeable.
 
 ```markdown
@@ -206,7 +206,7 @@ space. Alternatively, use a dash (`-`) or a plus sign (`+`) instead of an asteri
 + Lightning
 ```
 
-To create a numbered list, precede each of the list's items with the number of the step, then a period (`.`) and a space. 
+To create a numbered list, precede each of the list's items with the number of the step, then a period (`.`) and a space.
 
 ```markdown
 1. Give the sloth some food.
@@ -215,8 +215,8 @@ To create a numbered list, precede each of the list's items with the number of t
 4. Put the sloth to bed.
 ```
 
-To create a term list, precede each term with a dash (`-`) and a 
-space, the `term` keyword, and another space. Then add a colon (`:`), a space, and the definition after the term. 
+To create a term list, precede each term with a dash (`-`) and a
+space, the `term` keyword, and another space. Then add a colon (`:`), a space, and the definition after the term.
 
 ```markdown
 - term Ice: Ice sloths thrive below freezing temperatures.
@@ -225,8 +225,8 @@ space, the `term` keyword, and another space. Then add a colon (`:`), a space, a
 - term Lightning: Lightning sloths thrive in stormy climates.
 ```
 
-A list item's text, including terms and their definitions, can use the same 
-style attributes as other text, and include links to other content, including 
+A list item's text, including terms and their definitions, can use the same
+style attributes as other text, and include links to other content, including
 symbols.
 
 <!-- Copyright (c) 2021-2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->
diff --git a/Tests/SwiftDocCTests/Checker/Checkers/InvalidCodeBlockOptionTests.swift b/Tests/SwiftDocCTests/Checker/Checkers/InvalidCodeBlockOptionTests.swift
index 2def720f1..e67b5d8ff 100644
--- a/Tests/SwiftDocCTests/Checker/Checkers/InvalidCodeBlockOptionTests.swift
+++ b/Tests/SwiftDocCTests/Checker/Checkers/InvalidCodeBlockOptionTests.swift
@@ -24,7 +24,6 @@ let a = 1
         var checker = InvalidCodeBlockOption(sourceFile: nil)
         checker.visit(document)
         XCTAssertTrue(checker.problems.isEmpty)
-        XCTAssertEqual(RenderBlockContent.CodeListing.knownOptions, ["nocopy"])
     }
 
     func testOption() {
@@ -67,7 +66,7 @@ let c = 3
 let d = 4
 ```         
 
-```unknown, nocpoy
+```haskell, nocpoy
 let e = 5
 ```
 
@@ -104,5 +103,59 @@ let g = 7
 
         }
     }
+
+    func testLanguageNotFirst() {
+        let markupSource = """
+```nocopy, swift, highlight=[1]
+let b = 2
+```
+"""
+        let document = Document(parsing: markupSource, options: [])
+        var checker = InvalidCodeBlockOption(sourceFile: URL(fileURLWithPath: #file))
+        checker.visit(document)
+        XCTAssertEqual(1, checker.problems.count)
+
+        for problem in checker.problems {
+            XCTAssertEqual("org.swift.docc.InvalidCodeBlockOption", problem.diagnostic.identifier)
+            XCTAssertEqual(problem.diagnostic.summary, "Unknown option 'swift' in code block.")
+            XCTAssertEqual(problem.possibleSolutions.map(\.summary), ["If 'swift' is the language for this code block, then write 'swift' as the first option."])
+        }
+    }
+
+    func testInvalidHighlightIndex() throws {
+        let markupSource = """
+```swift, nocopy, highlight=[2]
+let b = 2
+```
+"""
+        let document = Document(parsing: markupSource, options: [])
+        var checker = InvalidCodeBlockOption(sourceFile: URL(fileURLWithPath: #file))
+        checker.visit(document)
+        XCTAssertEqual(1, checker.problems.count)
+        let problem = try XCTUnwrap(checker.problems.first)
+
+        XCTAssertEqual("org.swift.docc.InvalidCodeBlockOption", problem.diagnostic.identifier)
+        XCTAssertEqual(problem.diagnostic.summary, "Invalid 'highlight' index in '[2]' for a code block with 1 line. Valid range is 1...1.")
+        XCTAssertEqual(problem.possibleSolutions.map(\.summary), ["If you intended the last line, change '2' to 1."])
+    }
+
+    func testInvalidHighlightandStrikeoutIndex() throws {
+        let markupSource = """
+```swift, nocopy, highlight=[0], strikeout=[-1, 4]
+let a = 1
+let b = 2
+let c = 3
+```
+"""
+        let document = Document(parsing: markupSource, options: [])
+        var checker = InvalidCodeBlockOption(sourceFile: URL(fileURLWithPath: #file))
+        checker.visit(document)
+        XCTAssertEqual(2, checker.problems.count)
+
+        XCTAssertEqual("org.swift.docc.InvalidCodeBlockOption", checker.problems[0].diagnostic.identifier)
+        XCTAssertEqual(checker.problems[0].diagnostic.summary, "Invalid 'highlight' index in '[0]' for a code block with 3 lines. Valid range is 1...3.")
+        XCTAssertEqual(checker.problems[1].diagnostic.summary, "Invalid 'strikeout' indexes in '[-1, 4]' for a code block with 3 lines. Valid range is 1...3.")
+        XCTAssertEqual(checker.problems[1].possibleSolutions.map(\.summary), ["If you intended the last line, change '4' to 3."])
+    }
 }
 
diff --git a/Tests/SwiftDocCTests/Model/RenderContentMetadataTests.swift b/Tests/SwiftDocCTests/Model/RenderContentMetadataTests.swift
index 3d7d0c44e..b80312614 100644
--- a/Tests/SwiftDocCTests/Model/RenderContentMetadataTests.swift
+++ b/Tests/SwiftDocCTests/Model/RenderContentMetadataTests.swift
@@ -54,7 +54,7 @@ class RenderContentMetadataTests: XCTestCase {
             RenderInlineContent.text("Content"),
         ])
         
-        let code = RenderBlockContent.codeListing(.init(syntax: nil, code: [], metadata: metadata, copyToClipboard: false))
+        let code = RenderBlockContent.codeListing(.init(syntax: nil, code: [], metadata: metadata, options: nil))
         let data = try JSONEncoder().encode(code)
         let roundtrip = try JSONDecoder().decode(RenderBlockContent.self, from: data)
         
diff --git a/Tests/SwiftDocCTests/Model/RenderNodeSerializationTests.swift b/Tests/SwiftDocCTests/Model/RenderNodeSerializationTests.swift
index 0f669cd1c..fc63eb88e 100644
--- a/Tests/SwiftDocCTests/Model/RenderNodeSerializationTests.swift
+++ b/Tests/SwiftDocCTests/Model/RenderNodeSerializationTests.swift
@@ -44,7 +44,7 @@ class RenderNodeSerializationTests: XCTestCase {
                     .strong(inlineContent: [.text("Project > Run")]),
                     .text(" menu item, or the following code:"),
                 ])),
-                .codeListing(.init(syntax: "swift", code: ["xcrun xcodebuild -h", "xcrun xcodebuild build -configuration Debug"], metadata: nil, copyToClipboard: false)),
+                .codeListing(.init(syntax: "swift", code: ["xcrun xcodebuild -h", "xcrun xcodebuild build -configuration Debug"], metadata: nil, options: nil)),
             ]))
         ]
         
@@ -71,16 +71,16 @@ class RenderNodeSerializationTests: XCTestCase {
         let assessment1 = TutorialAssessmentsRenderSection.Assessment(title: [.paragraph(.init(inlineContent: [.text("Lorem ipsum dolor sit amet?")]))],
                                                                      content: nil,
                                                                      choices: [
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["override func viewDidLoad() {", "super.viewDidLoad()", "}"], metadata: nil, copyToClipboard: false))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "That's right!"),
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, copyToClipboard: false))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: "Not quite."),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["override func viewDidLoad() {", "super.viewDidLoad()", "}"], metadata: nil, options: nil))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "That's right!"),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, options: nil))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: "Not quite."),
             .init(content: [.paragraph(.init(inlineContent: [.text("None of the above.")]))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: nil),
         ])
         
         let assessment2 = TutorialAssessmentsRenderSection.Assessment(title: [.paragraph(.init(inlineContent: [.text("Duis aute irure dolor in reprehenderit?")]))],
                                                                      content: [.paragraph(.init(inlineContent: [.text("What is the airspeed velocity of an unladen swallow?")]))],
                                                                      choices: [
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["super.viewWillAppear()"], metadata: nil, copyToClipboard: false))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Correct."),
-            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, copyToClipboard: false))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Yep."),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["super.viewWillAppear()"], metadata: nil, options: nil))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Correct."),
+            .init(content: [.codeListing(.init(syntax: "swift", code: ["sceneView.delegate = self"], metadata: nil, options: nil))], isCorrect: true, justification: [.paragraph(.init(inlineContent: [.text("It's correct because...")]))], reaction: "Yep."),
             .init(content: [.paragraph(.init(inlineContent: [.text("None of the above.")]))], isCorrect: false, justification: [.paragraph(.init(inlineContent: [.text("It's incorrect because...")]))], reaction: "Close!"),
         ])
         
diff --git a/Tests/SwiftDocCTests/Rendering/RenderContentCompilerTests.swift b/Tests/SwiftDocCTests/Rendering/RenderContentCompilerTests.swift
index ef3604fd9..28af2d014 100644
--- a/Tests/SwiftDocCTests/Rendering/RenderContentCompilerTests.swift
+++ b/Tests/SwiftDocCTests/Rendering/RenderContentCompilerTests.swift
@@ -13,6 +13,8 @@ import Markdown
 @testable import SwiftDocC
 import XCTest
 
+typealias Position = RenderBlockContent.CodeBlockOptions.Position
+
 class RenderContentCompilerTests: XCTestCase {
     func testLinkOverrideTitle() async throws {
         let (bundle, context) = try await testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
@@ -245,7 +247,7 @@ class RenderContentCompilerTests: XCTestCase {
             return
         }
 
-        XCTAssertEqual(codeListing.copyToClipboard, true)
+        XCTAssertEqual(codeListing.options?.copyToClipboard, true)
     }
 
     func testNoCopyToClipboard() async throws {
@@ -269,7 +271,32 @@ class RenderContentCompilerTests: XCTestCase {
             return
         }
 
-        XCTAssertEqual(codeListing.copyToClipboard, false)
+        XCTAssertEqual(codeListing.options?.copyToClipboard, false)
+    }
+
+    func testCopyToClipboardNoLang() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockAnnotationsEnabled)
+
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```nocopy
+        let x = 1
+        ```
+        """#
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        XCTAssertEqual(codeListing.syntax, nil)
+        XCTAssertEqual(codeListing.options?.copyToClipboard, false)
     }
 
     func testCopyToClipboardNoFeatureFlag() async throws {
@@ -282,7 +309,6 @@ class RenderContentCompilerTests: XCTestCase {
         ```
         """#
         let document = Document(parsing: source)
-
         let result = document.children.flatMap { compiler.visit($0) }
 
         let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
@@ -291,7 +317,7 @@ class RenderContentCompilerTests: XCTestCase {
             return
         }
 
-        XCTAssertEqual(codeListing.copyToClipboard, false)
+        XCTAssertEqual(codeListing.options?.copyToClipboard, nil)
     }
 
     func testNoCopyToClipboardNoFeatureFlag() async throws {
@@ -314,6 +340,373 @@ class RenderContentCompilerTests: XCTestCase {
         }
 
         XCTAssertEqual(codeListing.syntax, "swift, nocopy")
-        XCTAssertEqual(codeListing.copyToClipboard, false)
+        XCTAssertEqual(codeListing.options?.copyToClipboard, nil)
+    }
+
+    func testShowLineNumbers() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockAnnotationsEnabled)
+
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```swift, showLineNumbers
+        let a = 1
+        let b = 2
+        let c = 3
+        let d = 4
+        let e = 5
+        ```
+        """#
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        XCTAssertEqual(codeListing.options?.showLineNumbers, true)
+    }
+
+    func testLowercaseShowLineNumbers() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockAnnotationsEnabled)
+
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```swift, showlinenumbers
+        let a = 1
+        let b = 2
+        let c = 3
+        let d = 4
+        let e = 5
+        ```
+        """#
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        XCTAssertEqual(codeListing.options?.showLineNumbers, true)
+    }
+
+    func testWrapAndHighlight() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockAnnotationsEnabled)
+
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```swift, wrap=20, highlight=[2]
+        let a = 1
+        let b = 2
+        let c = 3
+        let d = 4
+        let e = 5
+        ```
+        """#
+
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        XCTAssertEqual(codeListing.syntax, "swift")
+        XCTAssertEqual(codeListing.options?.wrap, 20)
+        let line = Position(line: 2)
+        XCTAssertEqual(codeListing.options?.lineAnnotations,
+            [RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line..<line
+                )
+            ])
+    }
+
+    func testHighlight() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockAnnotationsEnabled)
+
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```swift, highlight=[2]
+        let a = 1
+        let b = 2
+        let c = 3
+        let d = 4
+        let e = 5
+        ```
+        """#
+
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        XCTAssertEqual(codeListing.syntax, "swift")
+        let line = Position(line: 2)
+        XCTAssertEqual(codeListing.options?.lineAnnotations,
+            [RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line..<line
+            )])
+    }
+
+    func testHighlightNoFeatureFlag() async throws {
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```swift, highlight=[2]
+        let a = 1
+        let b = 2
+        let c = 3
+        let d = 4
+        let e = 5
+        ```
+        """#
+
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        XCTAssertEqual(codeListing.syntax, "swift, highlight=[2]")
+        XCTAssertEqual(codeListing.options?.lineAnnotations, nil)
+    }
+
+    func testMultipleHighlight() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockAnnotationsEnabled)
+
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```swift, highlight=[1, 2, 3]
+        let a = 1
+        let b = 2
+        let c = 3
+        let d = 4
+        let e = 5
+        ```
+        """#
+
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        XCTAssertEqual(codeListing.syntax, "swift")
+
+        let line1 = Position(line: 1)
+        let line2 = Position(line: 2)
+        let line3 = Position(line: 3)
+        XCTAssertEqual(codeListing.options?.lineAnnotations,
+            [RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line1..<line1
+            ),
+             RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line2..<line2
+            ),
+            RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line3..<line3
+            )
+            ])
+    }
+
+    func testMultipleHighlightMultipleStrikeout() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockAnnotationsEnabled)
+
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```swift, strikeout=[3,5], highlight=[1, 2, 3]
+        let a = 1
+        let b = 2
+        let c = 3
+        let d = 4
+        let e = 5
+        ```
+        """#
+
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        XCTAssertEqual(codeListing.syntax, "swift")
+
+        let line1 = Position(line: 1)
+        let line2 = Position(line: 2)
+        let line3 = Position(line: 3)
+        let line5 = Position(line: 5)
+        XCTAssertEqual(codeListing.options?.lineAnnotations,
+         [RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line1..<line1
+            ),
+             RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line2..<line2
+            ),
+            RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line3..<line3
+            ),
+            RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "strikeout",
+                range: line3..<line3
+            ),
+            RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "strikeout",
+                range: line5..<line5
+            )
+            ])
+    }
+
+    func testLanguageNotFirstOption() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockAnnotationsEnabled)
+
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```showLineNumbers, highlight=[1, 2, 3], swift, wrap=20, strikeout=[3]
+        let a = 1
+        let b = 2
+        let c = 3
+        let d = 4
+        let e = 5
+        ```
+        """#
+
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        // we expect the language to be the first option in the language line, otherwise it remains nil.
+        XCTAssertEqual(codeListing.syntax, nil)
+        XCTAssertEqual(codeListing.options?.showLineNumbers, true)
+        XCTAssertEqual(codeListing.options?.wrap, 20)
+
+        let line1 = Position(line: 1)
+        let line2 = Position(line: 2)
+        let line3 = Position(line: 3)
+        XCTAssertEqual(codeListing.options?.lineAnnotations,
+            [RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line1..<line1
+            ),
+             RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line2..<line2
+            ),
+            RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line3..<line3
+            ),
+            RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "strikeout",
+                range: line3..<line3
+            )
+            ])
+    }
+
+    func testUnorderedArrayOptions() async throws {
+        enableFeatureFlag(\.isExperimentalCodeBlockAnnotationsEnabled)
+
+        let (bundle, context) = try await testBundleAndContext()
+        var compiler = RenderContentCompiler(context: context, bundle: bundle, identifier: ResolvedTopicReference(bundleID: bundle.id, path: "/path", fragment: nil, sourceLanguage: .swift))
+
+        let source = #"""
+        ```highlight=[5,3,4], strikeout=[3,1]
+        let a = 1
+        let b = 2
+        let c = 3
+        let d = 4
+        let e = 5
+        ```
+        """#
+
+        let document = Document(parsing: source)
+
+        let result = document.children.flatMap { compiler.visit($0) }
+
+        let renderCodeBlock = try XCTUnwrap(result[0] as? RenderBlockContent)
+        guard case let .codeListing(codeListing) = renderCodeBlock else {
+            XCTFail("Expected RenderBlockContent.codeListing")
+            return
+        }
+
+        let line1 = Position(line: 1)
+        let line3 = Position(line: 3)
+        let line4 = Position(line: 4)
+        let line5 = Position(line: 5)
+        XCTAssertEqual(codeListing.options?.lineAnnotations,
+            [RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line5..<line5
+            ),
+             RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line3..<line3
+            ),
+            RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "highlight",
+                range: line4..<line4
+            ),
+            RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "strikeout",
+                range: line3..<line3
+            ),
+            RenderBlockContent.CodeBlockOptions.LineAnnotation(
+                style: "strikeout",
+                range: line1..<line1
+            )
+            ])
     }
 }
diff --git a/Tests/SwiftDocCTests/Utility/ListItemExtractorTests.swift b/Tests/SwiftDocCTests/Utility/ListItemExtractorTests.swift
index cdf61e5f3..e7885428e 100644
--- a/Tests/SwiftDocCTests/Utility/ListItemExtractorTests.swift
+++ b/Tests/SwiftDocCTests/Utility/ListItemExtractorTests.swift
@@ -514,7 +514,7 @@ class ListItemExtractorTests: XCTestCase {
             // ```
             // Inner code block
             // ```
-            .codeListing(.init(syntax: nil, code: ["Inner code block"], metadata: nil, copyToClipboard: false)),
+            .codeListing(.init(syntax: nil, code: ["Inner code block"], metadata: nil, options: nil)),
 
             // > Warning: Inner aside, with ``ThirdNotFoundSymbol`` link
             .aside(.init(style: .init(asideKind: .warning), content: [
diff --git a/features.json b/features.json
index 31e8b0e7d..014b9bf65 100644
--- a/features.json
+++ b/features.json
@@ -1,7 +1,7 @@
 {
   "features": [
     {
-      "name": "code-blocks"
+      "name": "code-block-annotations"
     },
     {
       "name": "diagnostics-file"