Torchlight - the API for Syntax Highlighting

Take a look at this example, from the configuration file of Laravel Octane.

Most of the classes are completely unstyled!

return [
    'listeners' => [
        WorkerStarting::class => [                                      ❌
            EnsureUploadedFilesAreValid::class,                         ❌
        ],

        RequestReceived::class => [                                     ❌
            ...Octane::prepareApplicationForNextOperation(),            ❌
            ...Octane::prepareApplicationForNextRequest(),              ❌
        ],

        WorkerErrorOccurred::class => [                                 ❌
            ReportException::class,                                     ❌
            StopWorkerIfNecessary::class,                               ❌
        ],
    ],

    'warm' => [
        ...Octane::defaultServicesToWarm(),                             ❌
    ],
]

Wrong

Blade templates are completely wrong.

Take a look at the last couple of lines. What's going on there?

@if (count($records) === 1)                                             ❌
    I have one record!
@elseif (count($records) > 1)                                           ❌
    I have {{ count($records) }} records!                               ❌
@else
    I don't have <span class='font-bold'>any</span> records!            ❌
@endif                                                                  ❌

Wrong

It misses most of this JavaScript content as well.

fs.readdirSync(path.join(process.cwd(), 'posts')).forEach(slug => {     ❌
    let content = fs.readFileSync(                                      ❌
        path.join(process.cwd(), 'posts', slug),                        ❌
        'utf-8'
    )

    fs.writeFileSync(                                                   ❌
        path.join(process.cwd(), 'build', `${slug}.html`),              ❌
        md.render(content)                                              ❌
    )                                                                   ❌
})                                                                      ❌

Wrong

It always gets it right, even for esoteric stuff.

Use any available VS Code theme, or make your own.

It supports every language VS Code supports, and any language you can find a tmLanguage.json file for.

It requires no JavaScript. Really. Torchlight is an HTTP API with server-side clients. Fully highlighted HTML is sent to the browser. No FOUC.

Let's take a look at those examples again.

Highlight.js misses all the classes here.

return [
    'listeners' => [
        WorkerStarting::class => [                                      ❌
            EnsureUploadedFilesAreValid::class,                         ❌
        ],

        RequestReceived::class => [                                     ❌
            ...Octane::prepareApplicationForNextOperation(),            ❌
            ...Octane::prepareApplicationForNextRequest(),              ❌
        ],

        WorkerErrorOccurred::class => [                                 ❌
            ReportException::class,                                     ❌
            StopWorkerIfNecessary::class,                               ❌
        ],
    ],

    'warm' => [
        ...Octane::defaultServicesToWarm(),                             ❌
    ],
]

Torchlight correctly renders them all.

 1return [
 2    'listeners' => [
 3        WorkerStarting::class => [                                      ✅
 4            EnsureUploadedFilesAreValid::class,                         ✅
 5        ],
 6 
 7        RequestReceived::class => [                                     ✅
 8            ...Octane::prepareApplicationForNextOperation(),            ✅
 9            ...Octane::prepareApplicationForNextRequest(),              ✅
10        ],
11 
12        WorkerErrorOccurred::class => [                                 ✅
13            ReportException::class,                                     ✅
14            StopWorkerIfNecessary::class,                               ✅
15        ],
16    ],
17 
18    'warm' => [
19        ...Octane::defaultServicesToWarm(),                             ✅
20    ],
21]

Highlight.js doesn't support Blade at all.

@if (count($records) === 1)                                             ❌
    I have one record!
@elseif (count($records) > 1)                                           ❌
    I have {{ count($records) }} records!                               ❌
@else
    I don't have <span class='font-bold'>any</span> records!            ❌
@endif                                                                  ❌

Torchlight gets the Blade, PHP, and HTML right.

1@if (count($records) === 1)                                             ✅
2    I have one record!
3@elseif (count($records) > 1)                                           ✅
4    I have {{ count($records) }} records!                               ✅
5@else
6    I don't have <span class='font-bold'>any</span> records!            ✅
7@endif                                                                  ✅

Highlight.js doesn't correctly pick up the JavaScript methods

fs.readdirSync(path.join(process.cwd(), 'posts')).forEach(slug => {     ❌
    let content = fs.readFileSync(                                      ❌
        path.join(process.cwd(), 'posts', slug),                        ❌
        'utf-8'
    )

    fs.writeFileSync(                                                   ❌
        path.join(process.cwd(), 'build', `${slug}.html`),              ❌
        md.render(content)                                              ❌
    )                                                                   ❌
})                                                                      ❌

Torchlight correctly picks them all up.

 1fs.readdirSync(path.join(process.cwd(), 'posts')).forEach(slug => {     ✅
 2    let content = fs.readFileSync(                                      ✅
 3        path.join(process.cwd(), 'posts', slug),                        ✅
 4        'utf-8'
 5    )
 6 
 7    fs.writeFileSync(                                                   ✅
 8        path.join(process.cwd(), 'build', `${slug}.html`),              ✅
 9        md.render(content)                                              ✅
10    )                                                                   ✅
11})                                                                      ✅

Getting the highlighting right is table-stakes.

Torchlight focuses on the author experiences by helping you communicate your ideas clearly.

You can control the display of your code using comments in your code.

Using actual comments means no more messed up indentation or squiggly underlines in your editor.

No more indecipherable syntaxes to remember to put at the top of your file. Annotate with inline comments.

Let's look at some annotations.

Focus Your Reader's Attention

Quickly focus your reader's attention on the relevant portions of your code, while still giving the full context.

Hover over the block to bring the whole block into focus.

No JavaScript required! Just plain ol' CSS.

Take a look at the source tab to see how it's done using Torchlight's focus annotation.

Language: PHP
Theme: Github Dark

 1<?php
 2/**
 3 * Chunk the collection into chunks of the given size.
 4 *
 5 * @param int $size
 6 * @return static
 7 */
 8public function chunk($size)
 9{
10    if ($size <= 0) {
11        return new static;
12    }
13 
14    $chunks = [];
15 
16    foreach (array_chunk($this->items, $size, true) as $chunk) { 
17        $chunks[] = new static($chunk); 
18    } 
19 
20    return new static($chunks);
21}

<?php
/**
 * Chunk the collection into chunks of the given size.
 *
 * @param int $size
 * @return static
 */
public function chunk($size)
{
    if ($size <= 0) {
        return new static;
    }

    $chunks = [];

    foreach (array_chunk($this->items, $size, true) as $chunk) { // [tl! **]
        $chunks[] = new static($chunk); // [tl! **]
    } // [tl! **]

    return new static($chunks);
}

Language: PHP. Theme: Github Dark

Clearly Visualize Differences Diffs

When explaining something in your docs or your blog posts, it's helpful to show your reader exactly what has changed.

Take a look at the source tab to see how it's done using Torchlight's diff annotation.

Language: PHP
Theme: Github Dark

 1<?php
 2/**
 3 * Chunk the collection into chunks of the given size.
 4