#Options

If you want to control something about a single line, you would use one of the many inline annotations that Torchlight offers.

To control something about an entire block, or perhaps your whole site, you would use "options" to achieve that.

#Available Options

Each of these is covered in detail on its own page, but here is an overview of each option and what it does.

• lineNumbers - turn line numbers on or off
• lineNumbersStart - the number of the first line
• lineNumbersStyle - the CSS style to apply to line numbers
• diffIndicators - turn on diff indicators (+/-)
• diffIndicatorsInPlaceOfLineNumbers - use the line number location for diff indicators
• summaryCollapsedIndicator - the text to show when a range is collapsed
• torchlightAnnotations - disable Torchlight annotation processing altogether.

#Setting Options Globally

There are two ways to pass in options. The first is globally, using the configuration file of your client. Each client will do it a little differently, but usually there is a configuration file where you can set the cache driver, host of the API, etc. In that same file you can set your global options.

Here is an example from the Laravel Client's torchlight.php file.

 1<?php
 2 
 3return [
 4    // Other settings...
 5 
 6    // Global options to control blocks-level settings.
 7    'options' => [
 8        // Turn line numbers on or off globally
 9        'lineNumbers' => true,
10 
11        // Control the `style` attribute applied to line numbers.
12        // 'lineNumbersStyle' => '',
13 
14        // Turn on +/- diff indicators.
15        'diffIndicators' => true,
16 
17        // If there are any diff indicators for a line, put them
18        // in place of the line number to save horizontal space.
19        'diffIndicatorsInPlaceOfLineNumbers' => true,
20 
21        // When lines are collapsed, this is the text that will
22        // be shown to indicate that they can be expanded.
23        // 'summaryCollapsedIndicator' => '...',
24    ]
25];

#Setting Options Per Block

Some blocks you'll want to set options individually. Any options you set on the block level will override that same option on the global level.

To set block level options, the first line of your block must be a comment, in the language of the block.

The comment must begin with torchlight! and be followed valid JSON.

Here is an example turning line numbers off for a single block:

 1// torchlight! {"lineNumbers": false}
 2return [
 3    'extensions' => [
 4        // Add attributes straight from markdown.
 5        AttributesExtension::class,
 6
 7        // Add Torchlight syntax highlighting.
 8        TorchlightExtension::class,
 9    ]
10]

return [
    'extensions' => [
        // Add attributes straight from markdown.
        AttributesExtension::class,
 
        // Add Torchlight syntax highlighting.
        TorchlightExtension::class,
    ]
]

Any option that you can set at the global level, you can set at the block level.