#Standalone CLI Client

🚨 This client is still very much a work in progress. Please open issues / PRs 🚨

View it on github at github.com/torchlight-api/torchlight-cli

The Torchlight CLI client is a Node CLI tool that can process any directory of HTML files and highlight <code> blocks using Torchlight.

#Installation

To install, require the package using NPM or Yarn

1npm i @torchlight-api/torchlight-cli

1yarn add @torchlight-api/torchlight-cli

#Init Command

Once you've added it to your project, you may run npx torchlight init to create a configuration file. Torchlight will place a torchlight.config.js file in the directory from which you run this command.

1npx torchlight init

If you'd like to customize the location of that file, you may pass the -p or --path option:

1# Custom configuration file location
2npx torchlight init --path config/torchlight.config.js

Scroll down to the Configuration File section to see all of the options.

#Highlight Command

To highlight .htm and .html files in your current working directory, you can run npx torchlight:

1# Look for .htm & .html files, highlighting them in place.
2npx torchlight

The highlight command has several different options you can pass to control the execution of the command.

 1Usage: torchlight|highlight [options] [command]
 2
 3Highlight code blocks in source files
 4
 5Options:
 6  -c, --config <file>       Path to the Torchlight configuration file.
 7  -i, --input <directory>   Input directory. Defaults to current directory.
 8  -o, --output <directory>  Output directory. Defaults to current directory.
 9  -n, --include <patterns>  Glob patterns used to search for source files.
10                            Separate multiple patterns with commas. Defaults
11                            to "**/*.htm,**/*.html".
12  -x, --exclude <patterns>  String patterns to ignore (not globs). Separate
13                            multiple patterns with commas. Defaults to
14                            "/node_modules/,/vendor/".
15  -w, --watch               Watch source files for changes
16  -h, --help                display help for command

#Config Path

By default Torchlight will look in the current directory for torchlight.config.js to use as your configuration file. If you'd like to change that location, you may pass a different path using the -c|--config option.

1# Use a custom path.
2npx torchlight --config config/torchlight.js

#Input and Output

The input and output directories both default to the current directory, meaning files will be modified in place, i.e. overwritten.

You may pass different paths using the -i|--input and -o|--output options.

1# Look in the `source` folder, output to the `build` folder.
2npx torchlight --input source --output build

#Include and Exclude

Torchlight searches your input directory for .htm and .html files, and ignores anything in a node_modules or vendor folder.

To change what is include, pass a comma separated list of globs to the -n|--include option.

To change what is excluded, pass a comma separated list of patterns (not globs) to the -x|--exclude option.

1# Add text files, ignore cache directory.
2npx torchlight --include "**/*.txt,**/*.htm,**/*.html" --exclude "/cache/"

#Watching Files

To continuously watch files in your input directory, pass the -w|--watch flag.

1# Continuously watch the source files.
2npx torchlight -w

#Cache Clear Command

To clear your cache, run npx torchlight cache:clear

#Configuration File

The configuration file may be published by running

1npx torchlight init

1# Custom configuration file location
2npx torchlight init --path config/torchlight.config.js

This will publish a file with contents similar to the following:

 1module.exports = {
 2    // Your token from https://torchlight.dev 
 3    token: process.env.TORCHLIGHT_TOKEN,
 4 
 5    // The Torchlight client caches highlighted code blocks. Here you
 6    // can define which directory you'd like to use. You'll likely
 7    // want to add this directory to your .gitignore. Set to
 8    // `false` to use an in-memory cache. You may also
 9    // provide a full cache implementation.
10    cache: 'cache',
11 
12    // Which theme you want to use. You can find all of the themes at
13    // https://torchlight.dev/docs/themes. 
14    theme: 'material-theme-palenight',
15 
16    // The Host of the API.
17    host: 'https://api.torchlight.dev',
18 
19    // Global options to control block-level settings.
20    // https://torchlight.dev/docs/options 
21    options: {
22        // Turn line numbers on or off globally.
23        lineNumbers: false,
24 
25        // Control the `style` attribute applied to line numbers.
26        // lineNumbersStyle: '',
27 
28        // Turn on +/- diff indicators.
29        diffIndicators: true,
30 
31        // If there are any diff indicators for a line, put them
32        // in place of the line number to save horizontal space.
33        diffIndicatorsInPlaceOfLineNumbers: true,
34 
35        // When lines are collapsed, this is the text that will
36        // be shown to indicate that they can be expanded.
37        // summaryCollapsedIndicator: '...',
38    },
39 
40    // Options for the highlight command.
41    highlight: {
42        // Directory where your un-highlighted source files live. If
43        // left blank, Torchlight will use the current directory.
44        input: '',
45 
46        // Directory where your highlighted files should be placed. If
47        // left blank, files will be modified in place.
48        output: '',
49 
50        // Globs to include when looking for files to highlight.
51        includeGlobs: [
52            '**/*.htm',
53            '**/*.html'
54        ],
55 
56        // String patterns to ignore (not globs). The entire file
57        // path will be searched and if any of these strings
58        // appear, the file will be ignored.
59        excludePatterns: [
60            '/node_modules/',
61            '/vendor/'
62        ]
63    }
64}

#Torchlight Token

Set your token from torchlight.dev. (Torchlight is completely free for personal and open source projects.) It defaults to the TORCHLIGHT_TOKEN environment variable. You can hardcode it if you please.

#Cache

Torchlight caches code blocks based on their contents and configuration, so that blocks that have already been rendered won't be rendered again. Use the cache key to control the directory in which the cache lives.

If you'd prefer to not use a file cache, you can set this to false and Torchlight will use an in-memory cache, which is only useful when watching files.

You can also provide your own cache implementation. Take a look at the Memory Cache to see what methods you need to implement.

#Theme

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

#Options

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

#Highlight

The options under the highlight key correspond to the options for the npx torchlight command.

Note: If you pass options in from the command line, they will override options in the configuration file.

#Setting the Language

Because your HTML files are likely generated from a static site generator, Torchlight looks in several places to try to decipher what language your <code> blocks are.

Torchlight first looks at the <code> block, and then the <pre> element that wraps it.

The following list is the order that Torchlight looks for the code language.

 1<!-- Look first at the code element -->
 2 
 3<!-- data-language attribute -->
 4<pre><code data-language='php'></code></pre>
 5<!-- data-lang attribute -->
 6<pre><code data-lang='php'></code></pre>
 7<!-- language-* class -->
 8<pre><code class='language-php'></code></pre>
 9<!-- lang-* class -->
10<pre><code class='lang-php'></code></pre>
11 
12<!-- Then look at the pre element -->
13 
14<!-- data-language attribute -->
15<pre data-language='php'><code></code></pre>
16<!-- data-lang attribute -->
17<pre data-lang='php'><code></code></pre>
18<!-- language-* class -->
19<pre class='language-php'><code></code></pre>
20<!-- lang-* class -->
21<pre class='lang-php'><code></code></pre>

If none of these line up with your static site generator, you may register a function in your configuration file to do the deciphering.

Register your function in the highlight block, under the decipherLanguageFromElement key in your torchlight.config.js file.

 1module.exports = {
 2    // ...
 3 
 4    highlight: {
 5        // Register your own deciphering function.
 6        decipherLanguageFromElement: function($pre) {
 7            // @TODO
 8        },
 9 
10        // ...
11    }
12}