Unlike traditional syntax highlighting tools, Torchlight is an HTTP API that tokenizes and highlights your code on our backend server instead of in the visitor's browser.
We find this to be the easiest and most powerful way to achieve accurate and feature rich syntax highlighting.
Client-side language parsers are limited in their complexity since they have to run in the browser environment. There are a lot of edge cases that those libraries can't catch.
Torchlight relies on the VS Code parsing engine and TextMate language grammars to achieve the most accurate results possible. We bring the power of the entire VS Code ecosystem to your docs or blog.
This means that you can also use all the VS Code themes you already know and love!
In writing the Torchlight rendering engine, we have put a huge emphasis on the joy of authoring your posts.
We found existing tools to be too cumbersome and unapproachable when it comes to helping you clearly communicate your ideas. Adding highlights, diffs, focus lines, etc requires a series of undecipherable 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 focus on a specific line, you can add an actual code comment with the magic syntax
[tl! highglight] and that line will be highlighted.
Using Torchlight to author the following block of PHP, focusing on lines 6 & 7, you would add two comments to your code.
1return [2 'extensions' => [3 // Add attributes straight from markdown.4 AttributesExtension::class,56 // Add Torchlight syntax highlighting. [tl! focus]7 TorchlightExtension::class, // [tl! focus]8 ]9]
And Torchlight would render the following:
1return [2 'extensions' => [3 // Add attributes straight from markdown.4 AttributesExtension::class,56 // 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 the leading
// comment syntax from line 7, leaving your code pristine.
Because annotations are actual code comments, it doesn't mess up your authoring experience by throwing invalid characters in your code. No more messed up indentation or squiggly underlines in your editor.
Annotations living alongside your examples keep them up-to-date and portable. If you add or remove lines from your examples, you don't have to go back through and recalculate which line numbers you want to highlight.
Using one of our first-party clients, Torchlight will look for all the code blocks on the page before the response is sent to the browser. After it has gathered all the blocks it sends them to the API to be highlighted, caches them, and swaps them into the response.
Each client works slightly differently. To read more about how your particular client works, you can check the client-specific documentation.