Setting Up Torchlight
Adam Bailey • September 16, 2021
configurationWhen 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.dev!
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.
Installation
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.
- Install the composer package:
1composer require torchlight/torchlight-jigsaw
- Add the following line to the very bottom of
bootstrap.php
at the root of your Jigsaw project, following theafterBuild()
methods:
1\Torchlight\Jigsaw\TorchlightExtension::make($container, $events)->boot();
- Publish the Torchlight configuration file with the following command:
1./vendor/bin/jigsaw torchlight:install
- 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:
1TORCHLIGHT_API_TOKEN=
- Your API token will be referenced in the
'token'
section of thetorchlight.php
config file.
1'token' => getenv('TORCHLIGHT_API_TOKEN'),
- Replace the tailwind styles that come with Jigsaw for
code
andpre
(found insource/_assets/sass/_base.scss
), with the following basic styles which they recommend:
1pre { 2 @apply my-4 rounded overflow-x-auto; 3} 4 5pre code.torchlight { 6 @apply block py-4 min-w-max; 7} 8 9pre code.torchlight .line {10 @apply px-4;11}12 13pre code.torchlight .line-number,14pre code.torchlight .summary-caret {15 @apply mr-4;16}
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.
- 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.
- Remove
"highlight.js"
frompackage.json
. - Remove all the
hljs
items fromsource/_assets/js/main.js
. - Remove the
highlight.js
import fromsource/_assets/sass/main.scss
. - And finally, remove the
/hljs/
item from theoptions.safeList
array intailwind.config.js
All done!
Reflection
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.