Syntax Highlighting Features

DocumenterShiki adds special syntax for highlighting specific lines in code blocks.

1. Line Range Syntax

Highlight specific lines using @highlight: comment at the beginning of the code block:

# @highlight: 2,4-5
function example()
    x = 1  # This line will be highlighted
    y = 2
    z = x + y  # These lines will be highlighted
    return z   # These lines will be highlighted
end

Line Numbers: Line counting starts from line 1 (the first line after the @highlight: comment). The @highlight: comment itself is not counted and will be removed from the output.

Usage:

@highlight: 2 - Highlight line 2
@highlight: 1,3 - Highlight lines 1 and 3
@highlight: 2-5 - Highlight lines 2 through 5
@highlight: 1,3-4,7 - Combine multiple ranges

Working Example:

# @highlight: 2,4-5
function example()
    x = 1  # This line will be highlighted
    y = 2
    z = x + y  # These lines will be highlighted
    return z   # These lines will be highlighted
end

example (generic function with 1 method)

2. Block Syntax

Highlight multiple consecutive lines using @highlight-start and @highlight-end.

Line Range: Highlighting starts from the line after @highlight-start and ends at the line before @highlight-end. The marker comments themselves are removed from the output.

Standalone `@highlight-end` (Separate Line)

When @highlight-end is placed on its own line, that line is removed from the output and the highlighting ends at the line before it:

function example()
    println("Normal line")
    # @highlight-start
    x = 10 * 2
    y = x + 5
    # @highlight-end
    println("Normal line")
    return y
end

In this pattern:

Highlighting starts after # @highlight-start (from the x = ... line)
Highlighting ends before # @highlight-end (the y = ... line is the last highlighted line)
The # @highlight-end line itself is removed from the output

Working Example:

function example()
    println("Normal line")
    # @highlight-start
    x = 10 * 2
    y = x + 5
    # @highlight-end
    println("Normal line")
    return y
end

example (generic function with 1 method)

Inline `@highlight-end` (Same Line as Code)

You can place @highlight-end on the same line as the last line you want to highlight. In this case, that line is highlighted and the marker is simply removed:

function example()
    println("Normal line")
    # @highlight-start
    x = 10 * 2
    y = x + 5  # @highlight-end
    println("Normal line")
    return y
end

In this pattern:

Highlighting starts after # @highlight-start (from the x = ... line)
Highlighting includes the line with # @highlight-end (the y = ... line is highlighted)
Only the # @highlight-end marker is removed, the code on that line remains

Working Example:

function example()
    println("Normal line")
    # @highlight-start
    x = 10 * 2
    y = x + 5  # @highlight-end
    println("Normal line")
    return y
end

example (generic function with 1 method)

Usage:

Use standalone @highlight-end when you want a clear visual separation in your source
Use inline @highlight-end to include the last line in highlighting without an extra marker line
Both patterns are useful for highlighting logical blocks like error checking or initialization

3. Leveled Highlights

Use different highlight levels (1-4) to visualize nested code structures with different colors:

# @highlight-start[1]
function demo()
    # @highlight-start[2]
    for i in 1:3
        # @highlight-start[3]
        if i % 2 == 0
            # @highlight-start[4]
            println("Even: $i") # @highlight-end
        end # @highlight-end
    end # @highlight-end
end # @highlight-end

demo()

Line Range: Same as Block Syntax - highlighting starts from the line after the marker and ends at the line before the closing marker. All marker comments are removed from the output.

Colors:

Level 1: Yellow
Level 2: Red
Level 3: Green
Level 4: Blue

Usage:

@highlight-start[1] - Start level 1 highlight
Nest multiple levels to show code hierarchy
Useful for complex algorithms with multiple nesting levels

Working Example:

# @highlight-start[1]
function demo()
    # @highlight-start[2]
    for i in 1:3
        # @highlight-start[3]
        if i % 2 == 0
            # @highlight-start[4]
            println("Even: $i") # @highlight-end
        end # @highlight-end
    end # @highlight-end
end # @highlight-end

demo()

Even: 2

4. Auto-Leveled Highlights

Use @highlight-auto-start and @highlight-auto-end to automatically determine highlight levels based on nesting depth:

# @highlight-auto-start
function demo()
    # @highlight-auto-start
    for i in 1:3
        # @highlight-auto-start
        if i % 2 == 0
            # @highlight-auto-start
            println("Even: $i")
            # @highlight-auto-end
        end # @highlight-auto-end
    end # @highlight-auto-end
end # @highlight-auto-end

demo()

Line Range: Same as Block Syntax - highlighting starts from the line after the marker and ends at the line before the closing marker. All marker comments are removed from the output.

Automatic Level Assignment:

First nested level: Level 1 (Yellow)
Second nested level: Level 2 (Red)
Third nested level: Level 3 (Green)
Fourth nested level: Level 4 (Blue)
Fifth nested level and beyond: Level continues to increase (5, 6, 7...), but colors cycle through 1-4

Usage:

@highlight-auto-start - Start automatic highlight (level determined by depth)
@highlight-auto-end - End automatic highlight
No need to manually specify level numbers
Useful when you want automatic color coding based on nesting structure

Working Example:

# @highlight-auto-start
function demo()
    # @highlight-auto-start
    for i in 1:3
        # @highlight-auto-start
        if i % 2 == 0
            # @highlight-auto-start
            println("Even: $i")
            # @highlight-auto-end
        end # @highlight-auto-end
    end # @highlight-auto-end
end # @highlight-auto-end

demo()

Even: 2

Deep Nesting Example (5 levels - demonstrating color cycling):

# @highlight-auto-start
function process_data(data)
    # @highlight-auto-start
    for item in data
        # @highlight-auto-start
        if item > 0
            # @highlight-auto-start
            while item > 10
                # @highlight-auto-start
                item = item - 5
                println("Reduced: $item")
                # @highlight-auto-end
            end # @highlight-auto-end
            println("Final: $item")
        end # @highlight-auto-end
    end # @highlight-auto-end
end # @highlight-auto-end

process_data([15, 8, 22])

# @highlight-auto-start
function process_data(data)
    # @highlight-auto-start
    for item in data
        # @highlight-auto-start
        if item > 0
            # @highlight-auto-start
            while item > 10
                # @highlight-auto-start
                item = item - 5
                println("Reduced: $item")
                # @highlight-auto-end
            end # @highlight-auto-end
            println("Final: $item")
        end # @highlight-auto-end
    end # @highlight-auto-end
end # @highlight-auto-end

process_data([15, 8, 22])

Reduced: 10
Final: 10
Final: 8
Reduced: 17
Reduced: 12
Reduced: 7
Final: 7

Note: Level 5 uses the same color as Level 1 (yellow), demonstrating color cycling while maintaining distinct level numbers.

Custom Background Color

You can specify a custom background color using the bgcolor option:

# @highlight-auto-start,bgcolor=lightpink
function calculate(x, y)
    # @highlight-auto-start,bgcolor=#ffeecc
    result = x + y
    println("Result: $result")
    # @highlight-auto-end
    return result
end # @highlight-auto-end

calculate(5, 3)

Working Example:

# @highlight-auto-start,bgcolor=lightpink
function calculate(x, y)
    # @highlight-auto-start,bgcolor=#ffeecc
    result = x + y
    println("Result: $result")
    # @highlight-auto-end
    return result
end # @highlight-auto-end

calculate(5, 3)

Color specification:

Hex colors: bgcolor=#ffcc00, bgcolor=#90ee90
Named colors: bgcolor=lightblue, bgcolor=lightcoral, bgcolor=lightyellow

This is useful for emphasizing specific code sections with distinctive colors.

5. Inline Comment Syntax

Highlight specific lines using [!code highlight] in comments (compatible with Shiki transformers):

function example()
    x = 1
    y = 2  # [!code highlight]
    return x + y
end

For multiple consecutive lines:

function example()
    x = 1  # [!code highlight:3]
    y = 2
    z = 3
    return x + y + z
end

Usage:

Add # [!code highlight] at the end of the line to highlight
Add # [!code highlight:N] to highlight N consecutive lines starting from that line
Compatible with standard Shiki notation

Note: The [!code highlight] syntax does not support custom bgcolor= specification. For custom background colors, use the @highlight-auto-start,bgcolor=... syntax instead (see Section 4).

Working Example:

function example()
    x = 1  # [!code highlight:3]
    y = 2
    z = 3
    return x + y + z
end

example (generic function with 1 method)

6. REPL-Style Code Highlighting

For REPL-style code examples, use the inline comment syntax [!code highlight]:

julia> x = [1, 2, 3, 4, 5]  # [!code highlight]
5-element Vector{Int64}:
 1
 2
 3
 4
 5

julia> sum(x)  # [!code highlight]
15

Working Example:

julia> x = [1, 2, 3, 4, 5]  # [!code highlight]
5-element Vector{Int64}:
 1
 2
 3
 4
 5

julia> sum(x)  # [!code highlight]
15

This approach works well for static REPL examples where you want to highlight specific commands.

When to Use Each Syntax

Line Range Syntax: When you need to highlight specific, non-consecutive lines
Block Syntax: For highlighting logical blocks (error checking, initialization, etc.)
Leveled Highlights: For visualizing nested structures and code hierarchy with manual control
Auto-Leveled Highlights: For automatic color coding based on nesting depth without manual level management
Inline Comment Syntax: For quick, ad-hoc highlighting of individual lines