#Collapsing Sections

Sometimes in your documentation or a blog post, you want to focus the reader on a specific block of code, but allow them to see the rest of the code if they need to.

One way you can achieve that is by using the focus annotation to blur the irrelevant code, but you can also use Torchlight to collapse blocks of code using native HTML, no JavaScript required.

In this example, we're going to collapse the heading_permalink options, as they might distract from the point of the example.

We can do this by using the collapse annotation:

 1return [
 2    'heading_permalink' => [ // [tl! collapse:start]
 3        'html_class' => 'permalink',
 4        'id_prefix' => 'user-content',
 5        'insert' => 'before',
 6        'title' => 'Permalink',
 7        'symbol' => '#',
 8    ], // [tl! collapse:end]
 9
10    'extensions' => [
11        // Add attributes straight from markdown.
12        AttributesExtension::class,
13
14        // Add Torchlight syntax highlighting.
15        TorchlightExtension::class,
16    ]
17]

 1return [
 2    'heading_permalink' => [ ...
 3        'html_class' => 'permalink',
 4        'id_prefix' => 'user-content',
 5        'insert' => 'before',
 6        'title' => 'Permalink',
 7        'symbol' => '#',
 8    ], 
 9 
10    'extensions' => [
11        // Add attributes straight from markdown.
12        AttributesExtension::class,
13 
14        // Add Torchlight syntax highlighting.
15        TorchlightExtension::class,
16    ]
17]

These lines will now be wrapped in a summary / detail pair of tags, that allows the user to natively toggle the open and closed start of the block. Torchlight will also add a has-summaries class to your code tag anytime you define a summary range.

Click on line 2 and you'll see the full effect. Use your developer tools to inspect the element to see exactly how it works!

You can use the start end method of defining a range, or any of the other range modifiers.

Here's an example using the N-many modifier to collapse the 5 lines following the annotation:

 1return [
 2    'heading_permalink' => [ // [tl! collapse:5]
 3        'html_class' => 'permalink',
 4        'id_prefix' => 'user-content',
 5        'insert' => 'before',
 6        'title' => 'Permalink',
 7        'symbol' => '#',
 8    ],
 9
10    'extensions' => [
11        // Add attributes straight from markdown.
12        AttributesExtension::class,
13
14        // Add Torchlight syntax highlighting.
15        TorchlightExtension::class,
16    ]
17]

 1return [
 2    'heading_permalink' => [ ...
 3        'html_class' => 'permalink',
 4        'id_prefix' => 'user-content',
 5        'insert' => 'before',
 6        'title' => 'Permalink',
 7        'symbol' => '#',
 8    ],
 9 
10    'extensions' => [
11        // Add attributes straight from markdown.
12        AttributesExtension::class,
13 
14        // Add Torchlight syntax highlighting.
15        TorchlightExtension::class,
16    ]
17]

#Customizing the Summary Text

By default Torchlight will add a subtle ... in place of the collapsed text, but you can customize that by passing in the summaryCollapsedIndicator options:

 1// torchlight! {"summaryCollapsedIndicator": "Click to show ]"}
 2return [
 3    'heading_permalink' => [ // [tl! collapse:start]
 4        'html_class' => 'permalink',
 5        'id_prefix' => 'user-content',
 6        'insert' => 'before',
 7        'title' => 'Permalink',
 8        'symbol' => '#',
 9    ], // [tl! collapse:end]
10
11    'extensions' => [
12        // Add attributes straight from markdown.
13        AttributesExtension::class,
14
15        // Add Torchlight syntax highlighting.
16        TorchlightExtension::class,
17    ]
18]

 1return [
 2    'heading_permalink' => [ Click to show ]
 3        'html_class' => 'permalink',
 4        'id_prefix' => 'user-content',
 5        'insert' => 'before',
 6        'title' => 'Permalink',
 7        'symbol' => '#',
 8    ], 
 9 
10    'extensions' => [
11        // Add attributes straight from markdown.
12        AttributesExtension::class,
13 
14        // Add Torchlight syntax highlighting.
15        TorchlightExtension::class,
16    ]
17]

#Required CSS

You will need to add the following CSS to your page to accomplish the hiding:

 1.torchlight summary:focus {
 2    outline: none;
 3}
 4 
 5/* Hide the default markers, as we provide our own */
 6.torchlight details > summary::marker,
 7.torchlight details > summary::-webkit-details-marker {
 8    display: none;
 9}
10 
11.torchlight details .summary-caret::after {
12    pointer-events: none;
13}
14 
15/* Add spaces to keep everything aligned */
16.torchlight .summary-caret-empty::after,
17.torchlight details .summary-caret-middle::after,
18.torchlight details .summary-caret-end::after {
19    content: " ";
20}
21 
22/* Show a minus sign when the block is open. */
23.torchlight details[open] .summary-caret-start::after {
24    content: "-";
25}
26 
27/* And a plus sign when the block is closed. */
28.torchlight details:not([open]) .summary-caret-start::after {
29    content: "+";
30}
31 
32/* Hide the [...] indicator when open. */
33.torchlight details[open] .summary-hide-when-open {
34    display: none;
35}
36 
37/* Show the [...] indicator when closed. */
38.torchlight details:not([open]) .summary-hide-when-open {
39    display: initial;
40}

#Default to Open

By default, when you define a collapse range it will be collapsed. If you want to define the range but default it to open, you can add the open keyword:

 1return [
 2    'heading_permalink' => [ // [tl! collapse:start open]
 3        'html_class' => 'permalink',
 4        'id_prefix' => 'user-content',
 5        'insert' => 'before',
 6        'title' => 'Permalink',
 7        'symbol' => '#',
 8    ], // [tl! collapse:end]
 9
10    'extensions' => [
11        // Add attributes straight from markdown.
12        AttributesExtension::class,
13
14        // Add Torchlight syntax highlighting.
15        TorchlightExtension::class,
16    ]
17]

 1return [
 2    'heading_permalink' => [ ...
 3        'html_class' => 'permalink',
 4        'id_prefix' => 'user-content',
 5        'insert' => 'before',
 6        'title' => 'Permalink',
 7        'symbol' => '#',
 8    ], 
 9 
10    'extensions' => [
11        // Add attributes straight from markdown.
12        AttributesExtension::class,
13 
14        // Add Torchlight syntax highlighting.
15        TorchlightExtension::class,
16    ]
17]