#Jigsaw Torchlight Client

An extension for the static site builder Jigsaw, by Tighten.

#Installation

To install, require the package from composer:

1composer require torchlight/torchlight-jigsaw

After the package is downloaded, add the following line to your bootstrap.php

1\Torchlight\Jigsaw\TorchlightExtension::make($container, $events)->boot();

This will boot the extension so that it can register its bindings, events, and commands.

Now your bootstrap.php might look something like this:

 1<?php
 2 
 3use App\Listeners\GenerateSitemap;
 4use TightenCo\Jigsaw\Jigsaw;
 5 
 6/** @var $container \Illuminate\Container\Container */
 7/** @var $events \TightenCo\Jigsaw\Events\EventBus */
 8 
 9/**
10 * You can run custom code at different stages of the build process by
11 * listening to the 'beforeBuild', 'afterCollections', and 'afterBuild' events.
12 *
13 * For example:
14 *
15 * $events->beforeBuild(function (Jigsaw $jigsaw) {
16 *     // Your code here
17 * });
18 */
19 
20$events->afterBuild(GenerateSitemap::class);
21 
22\Torchlight\Jigsaw\TorchlightExtension::make($container, $events)->boot();

#Configuration

To configure your Torchlight integration, you can start by publishing the configuration file:

1./vendor/bin/jigsaw torchlight:install

Once run, you should see a new torchlight.php file in the root of your project, with contents that look like this:

 1return [
 2    // Which theme you want to use. You can find all of the themes at
 3    // https://torchlight.dev/themes, or you can provide your own. 
 4    'theme' => 'material-theme-palenight',
 5 
 6    // Your API token from https://torchlight.dev. You can set it 
 7    // as an ENV variable (shown below), or just hardcode it if
 8    // your repo is private.
 9    'token' => getenv('TORCHLIGHT_API_TOKEN'),
10 
11    // If you want to register the blade directives, set this to true.
12    'blade_components' => true,
13 
14    // The Host of the API.
15    'host' => 'https://api.torchlight.dev',
16 
17    // If you want to specify the cache path, you can do so here. Note
18    // that you should *not* use the same path that Jigsaw uses,
19    // which is `cache` at the root level of your app.
20    'cache_path' => 'torchlight_cache',
21 
22    // Because of the way Jigsaw works as a static site generator, all the
23    // code blocks for your entire site will be sent as one request. We
24    // increase the timeout to 15 seconds to cover for that.
25    'request_timeout' => 15,
26 
27    // Global options to control blocks-level settings.
28    // https://torchlight.dev/docs/options 
29    'options' => [
30        // Turn line numbers on or off globally.
31        'lineNumbers' => true,
32 
33        // Control the `style` attribute applied to line numbers.
34        // 'lineNumbersStyle' => '',
35 
36        // Turn on +/- diff indicators.
37        'diffIndicators' => true,
38 
39        // If there are any diff indicators for a line, put them
40        // in place of the line number to save horizontal space.
41        'diffIndicatorsInPlaceOfLineNumbers' => true,
42 
43        // When lines are collapsed, this is the text that will
44        // be shown to indicate that they can be expanded.
45        // 'summaryCollapsedIndicator' => '...',
46    ]
47];

#Theme

You can change the theme of all your code blocks by adjusting the theme key in your configuration. To view themes provided by Torchlight, head over to torchlight.dev/themes.

#Token

This is your API token from torchlight.dev. (Torchlight is completely free for personal and open source projects.)

#Blade Components

Torchlight provides a custom Laravel Blade component. If you'd like to disable the registration of the component for whatever reason, you can set this to false.

Note: If you disable the blade component, the markdown rendering still works.

#Cache

Torchlight requires a separate cache path, distinct from the Jigsaw cache. Jigsaw cleans out its cache from time to time, whereas Torchlight depends on individual TTLs, courtesy of the Laravel cache driver.

You may want to add your configured cache path (/torchlight_cache/) to your .gitignore file so that the cache files aren't persisted to your git history.

#Request Timeout

Because Jigsaw is a static site generator, we bump the request timeout up to 15 seconds to cover very large sites. It's unlikely you'll need to change this.

#Options

These are options that you can set to control every code block on your site. Read more in the options section.

#Markdown

To use Torchlight in your Jigsaw markdown files, you don't need to do anything else beside using fenced code blocks like you have been.

1This is my great markdown file! I'm going to show some code now:
2
3```php
4echo "here is my code";
5```
6
7Wasn't that good code?

Torchlight will handle highlighting that block of code.

If you want to add additional classes or an ID, you can use the syntax that is supported by Jigsaw's underlying markdown parser.

1This is my great markdown file! I'm going to show some code now:
2
3```php {#some-html-id.mt-4.mb-8}
4echo "here is my code"
5```
6
7Wasn't that good code?

The resulting code element will have an id of some-html-id and classes of mt-4 mb-8, along with any classes that Torchlight applies.

#Specifying the Block Theme

When using markdown, you can specify a theme per block by appending :theme-name to the language name, e.g. php:github-dark

1This is my great markdown file! I'm going to show some code now:
2
3```php:github-dark 
4echo "here is my code";
5```
6
7Wasn't that good code?

Regardless of the value in your torchlight.php configuration file, this block will be rendered with the github-dark theme.

#Blade Component

If you want to use Torchlight in your .blade.php files, you can use the custom blade component x-torchlight-code.

1<pre><x-torchlight-code language='php'>
2    echo "hello world";
3</x-torchlight-code></pre>

To read more about the blade component and its options, check out the documentation for the standard Laravel client.

#Deploying

Because the Torchlight extension hooks into your Jigsaw build process and writes fully rendered HTML to your output directory, there is nothing special that you need to do when it comes to deploying your site.

No JavaScript, no keys, no tokens. If it looks right in your build directory it will be right when you ship it, since it's just HTML.