#Annotation Ranges

Sometimes you want to apply an annotation to a whole set of lines, without having to add dozens of comments.

We have provided several different methods to achieve this, so you may pick the one that best fits your use case.

#Cheat Sheet

We'll cover each of these in detail, but here is a cheat sheet of the available modifiers.

 1highlight          -- This line only
 2
 3highlight:start    -- The start of an open ended range
 4highlight:end      -- The end of an open ended range
 5
 6highlight:10       -- This line, and the 10 following lines
 7highlight:-10      -- This line, and the 10 preceding lines
 8
 9highlight:1,10     -- Start one line down, highlight 10 lines total
10highlight:-1,10    -- Start one line up, highlight 10 lines total

#Single Lines

By default, every annotation applies only to the line that it lives on.

For example, this will only highlight the line it is on, line number 2.

1return [
2    'extensions' => [ // [tl! highlight]
3        // Add attributes straight from markdown.
4        AttributesExtension::class,
5
6        // Add Torchlight syntax highlighting.
7        TorchlightExtension::class,
8    ]
9]

1return [
2    'extensions' => [ 
3        // Add attributes straight from markdown.
4        AttributesExtension::class,
5 
6        // Add Torchlight syntax highlighting.
7        TorchlightExtension::class,
8    ]
9]

#N-Many lines

To highlight the current line, and the next N lines, you may use the :N modifier.

In this example, we will highlight the current line (2) and the next two lines (3 & 4).

1return [
2    'extensions' => [ // [tl! highlight:2]
3        // Add attributes straight from markdown.
4        AttributesExtension::class,
5
6        // Add Torchlight syntax highlighting.
7        TorchlightExtension::class,
8    ]
9]

1return [
2    'extensions' => [ 
3        // Add attributes straight from markdown.
4        AttributesExtension::class,
5 
6        // Add Torchlight syntax highlighting.
7        TorchlightExtension::class,
8    ]
9]

This also works with negative numbers :-N

1return [
2    'extensions' => [
3        // Add attributes straight from markdown.
4        AttributesExtension::class,  // [tl! highlight:-2]
5
6        // Add Torchlight syntax highlighting.
7        TorchlightExtension::class,
8    ]
9]

1return [
2    'extensions' => [
3        // Add attributes straight from markdown.
4        AttributesExtension::class,  
5 
6        // Add Torchlight syntax highlighting.
7        TorchlightExtension::class,
8    ]
9]

#Offset and Length

If you have a bit of code that is hard to reach with a comment, perhaps a heredoc, you can use the focus:M,N syntax where M is the number of lines above or below the current line, and N is the number of lines to highlight.

Here we're going to start 6 lines down, and highlight 3 lines total.

 1// This is a long bit of text, hard to highlight the middle. [tl! highlight:6,3]
 2return <<<EOT
 3spring sunshine
 4the smell of waters
 5from the stars
 6
 7deep winter
 8the smell of a crow
 9from the stars
10
11beach to school
12the smell of water
13in the sky
14EOT;

 1// This is a long bit of text, hard to highlight the middle. 
 2return <<<EOT
 3spring sunshine
 4the smell of waters
 5from the stars
 6 
 7deep winter
 8the smell of a crow
 9from the stars
10 
11beach to school
12the smell of water
13in the sky
14EOT;

You can also start from the bottom by using a negative offset. We'll start 7 lines up and highlight 3 lines again.

 1// This is a long bit of text, hard to highlight the middle.
 2return <<<EOT
 3spring sunshine
 4the smell of waters
 5from the stars
 6
 7deep winter
 8the smell of a crow
 9from the stars
10
11beach to school
12the smell of water
13in the sky
14EOT; // [tl! highlight:-7,3]

 1// This is a long bit of text, hard to highlight the middle.
 2return <<<EOT
 3spring sunshine
 4the smell of waters
 5from the stars
 6 
 7deep winter
 8the smell of a crow
 9from the stars
10 
11beach to school
12the smell of water
13in the sky
14EOT; 

#Start and End

Sometimes you want to define a start and end line, and annotate everything in the middle.

You may do this with the :start and :end modifiers.

1return [
2    'extensions' => [  // Start here [tl! highlight:start]
3        // Add attributes straight from markdown.
4        AttributesExtension::class,
5
6        // Add Torchlight syntax highlighting.
7        TorchlightExtension::class,
8    ] // End here [tl! highlight:end]
9]

1return [
2    'extensions' => [  // Start here 
3        // Add attributes straight from markdown.
4        AttributesExtension::class,
5 
6        // Add Torchlight syntax highlighting.
7        TorchlightExtension::class,
8    ] // End here 
9]

#Supported Annotations

All of them! Ranges are supported for all of the Torchlight annotation keywords:

• highlight
• focus
• insert
• remove
• collapse
• autolink
• reindex

Custom classes and IDs are supported as well.

• .my-custom-class:start
• .my-custom-class:end
• .my-custom-class:1,10
• .my-custom-class:3
• .my-custom-class:-1,5

Torchlight also plays nicely with prefixed Tailwind classes:

• .sm:py-4:start
• .sm:py-4:end
• .sm:py-4:1,10
• .sm:py-4:3
• .sm:py-4:-1,5

Remember that an HTML ID must be unique on the page, so while it's unlikely that you'd want to apply an ID to a range of lines, you may want to apply it to a line you cannot reach.

For example, to reach four lines down and add an ID of popover-trigger, you could do the following:

 1// Reach down 4 lines, add the ID to one line [tl! #popover-trigger:4,1]
 2return <<<EOT
 3spring sunshine
 4the smell of waters
 5from the stars
 6
 7deep winter
 8the smell of a crow
 9from the stars
10
11beach to school
12the smell of water
13in the sky
14EOT;