Setting Up Torchlight

Adam Bailey • September 16, 2021



When I built my new portfolio, I used Jigsaw version 1.3, which has been amazing. However, it came pre-built with a JavaScript based syntax highlighting package which did not seem to correctly style certain blocks of PHP code. Then I heard about!

Torchlight to the rescue!

According to the official documentation for Torchlight:

"Torchlight is a VS Code-compatible syntax highlighter that requires no JavaScript, supports every language, every VS Code theme, line highlighting, git diffing, and more."

I had watched several other PHP devs start to use Torchlight for their personal sites, and it just looks beautiful. I decided it was time to make the switch, but I had no idea how easy it was going to be.

Follow along as I describe the process of swapping out the syntax highlighting packages in my portfolio site.


First, at this time Torchlight (version 0.2.1) requires you to sigh up for "early access", so you can get your API token(Torchlight is completely free for personal and open source projects.). I signed up through a link on their home page.

After I received the early access and my API token, I got started installing the Jigsaw Client. Torchlight's full documentation for this installation is fully sufficient. You can really stop reading this now and just use that doc, but I'm still going to describe the process I took.

  1. Install the composer package:
1composer require torchlight/torchlight-jigsaw
  1. Add the following line to the very bottom of bootstrap.php at the root of your Jigsaw project, following the afterBuild() methods:
1\Torchlight\Jigsaw\TorchlightExtension::make($container, $events)->boot();
  1. Publish the Torchlight configuration file with the following command:
1./vendor/bin/jigsaw torchlight:install
  1. Add an .env file in the root of your Jigsaw project, and add the file to .gitignore so it isn't in your repository. in .env, add this line including your token:
  1. Your API token will be referenced in the 'token' section of the torchlight.php config file.
1'token' => getenv('TORCHLIGHT_API_TOKEN'),
  1. Replace the tailwind styles that come with Jigsaw for code and pre (found in source/_assets/sass/_base.scss), with the following basic styles which they recommend:
1pre {
2 @apply my-4 rounded overflow-x-auto;
5pre code.torchlight {
6 @apply block py-4 min-w-max;
9pre code.torchlight .line {
10 @apply px-4;
13pre code.torchlight .line-number,
14pre code.torchlight .summary-caret {
15 @apply mr-4;

Follow the options documentation for info on configuring themes and much more. For me, the configuration that it shipped with was absolutely perfect for my needs.

  1. Rebuild your Jigsaw site locally, and you should see the magic appear! You do not need to make any changes to the markdown files, Torchlight uses the same backtick/language syntax that highlight.js uses.

Clean Up!

We still need to remove the highlight.js dependency and all its configuration.

  1. Remove "highlight.js" from package.json.
  2. Remove all the hljs items from source/_assets/js/main.js.
  3. Remove the highlight.js import from source/_assets/sass/main.scss.
  4. And finally, remove the /hljs/ item from the options.safeList array in tailwind.config.js

All done!


You just made an amazing improvement to the code styling in your portfolio (and reduced the number of JavaScript dependencies, which to me is always a win)! There are so many other cool features in Torchlight, such as code highlighting, diffing, collapsing, and more!

I hope this short tutorial was an easy switch from the built-in code block styling that comes with Jigsaw. I know I like it and will use it for the foreseeable future.

You might like other posts in