#Inline Annotations

One of the things that makes Torchlight such a joy to author with is that you can control how your code is rendered via comments in the code you're writing.

If you want to highlight a specific line, you can add a code comment with the magic syntax [tl! highglight] and that line will be highlighted.

Gone are the days of inscrutable line number definitions at the top of your file, only to have them become outdated the moment you add or remove a line.

Most other tools use a series of line numbers up front to denote highlight or focus lines:

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

If you don't have the syntax memorized, it's hard to tell what those numbers mean. And of course when you add a line or remove a line, everything changes and you have to recalculate!

With Torchlight, you control your display with inline annotations in comments.

All inline annotations are wrapped within square brackets and start with tl!, leaving you with the following format: [tl! ... ... ...].

For example, if you are using Torchlight to render the following block of PHP:

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

and you wanted to draw attention to lines 6 & 7, you could focus those lines by using the focus annotation:

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

Resulting in the following:

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

Notice that Torchlight is smart enough to not only strip the annotation from line 6, but the annotation and comment syntax from line 7, leaving your code pristine.

If the entirety of the comment is Torchlight annotations, the comment will be removed from the rendered code. If there is additional content in the comment, that content will remain and the annotation will be stripped out.

Because annotations are actual code comments, it doesn't mess up your authoring experience by throwing invalid characters in your code.

Inline annotations support different keywords, modifiers, and range definitions.

• Annotating A Range of Lines
• Highlighting Lines
• Focusing Lines
• Expanding / Collapsing Sections
• Diffing Lines
• Adding Custom IDs & Classes
• Auto-linking URLs
• Changing Line Numbers

Remember that the comment syntax varies based on what language you are highlighting, so be sure to use actual comments.

For example if you're highlighting HTML, you would use HTML comment tags <!-- -->. See the example on line 5.

1<div class='text-7xl font-bold'>
2    <span>Syntax highlighting is</span>
3    <span class='font-bold'>
4        <span aria-hidden="true" class="absolute inset-0 bg-yellow-100 transform -rotate-6"></span>
5        <span>broken.</span> <!-- [tl! focus] -->
6    </span>
7</div>

1<div class='text-7xl font-bold'>
2    <span>Syntax highlighting is</span>
3    <span class='font-bold'>
4        <span aria-hidden="true" class="absolute inset-0 bg-yellow-100 transform -rotate-6"></span>
5        <span>broken.</span> 
6    </span>
7</div>

Annotations can be used with plain text and JSON, despite them having no "official" comment support as a language.

#Plain Text

For plain text, everything is treated "as if" it's a comment, so you can just put the annotation on any line.

 1spring sunshine
 2the smell of waters
 3from the stars
 4
 5deep winter [tl! focus:2]
 6the smell of a crow
 7from the stars
 8
 9beach to school
10the smell of water
11in the sky

 1spring sunshine
 2the smell of waters
 3from the stars
 4
 5deep winter 
 6the smell of a crow
 7from the stars
 8
 9beach to school
10the smell of water
11in the sky

#JSON

JSON uses the double slash // comment style, even though it's not official spec. Forgive us.

 1{
 2    "torchlightAnnotations": true,
 3    "lineNumbers": true, // [tl! focus:2]
 4    "lineNumbersStart": 1,
 5    "lineNumbersStyle": "text-align: right; -webkit-user-select: none; user-select: none;",
 6    "summaryCollapsedIndicator": "...",
 7 
 8    "diffIndicators": false,
 9    "diffIndicatorsInPlaceOfLineNumbers": true,
10}

 1{
 2    "torchlightAnnotations": true,
 3    "lineNumbers": true, 
 4    "lineNumbersStart": 1,
 5    "lineNumbersStyle": "text-align: right; -webkit-user-select: none; user-select: none;",
 6    "summaryCollapsedIndicator": "...",
 7 
 8    "diffIndicators": false,
 9    "diffIndicatorsInPlaceOfLineNumbers": true,
10}