Introduction

This add-on adds Highlight.js v 9.12.0 code highlighting to your pages.
All codeblocks are color-coded/highlighted according to the selected theme.

NOTE: Turn off the "debug bar" or else it will use the highlight-style from that!

Installation

Clone or Copy the files to their destination

Clone this project on your system:

cd YOUR_WEBFOLDER/site/addons
git clone https://github.com/mwesten/StatamicV2-Highlight-Addon.git Highlight

Or download the project and add the contents of archive to the site/addons/Highlight folder.

Add the highlight init code to your page

Open the theme file layout (for example) site/themes/redwood/layouts/default.html
Add the following code in your <head> section:{{noparse}}

{{ highlight }}
{{/noparse}}

This displays the highlight.js in the default theme.

If you like you can add the code just before your body close tag instead of in your <head>. This is a matter of preference.

Configuring Highlight.js

You can select one of the added themes that you can find in the site/addons/Highlight/resources/css folder; for example the Sunburst theme can be selected by adding the style parameter to the tag:{{noparse}}

{{ highlight style="sunburst"}}
{{/noparse}}

If you like a cleaner option (and one that will be configurable from the Control Panel in the future), you should use the config-file.

Create the file highlight.yaml in the folder site/settings/addons and add the following lines:

codestyle: monokai
library_version: small

The line codestyle contains the themename as can be found in the site/addons/Highlight/resources/css folder. Make sure you don't also us the parameter option... That overrides this option!

The library_version can be one of these options: small, medium or large.
This specifies what version of the Highlight.js script will be used.
small contains the basic options displayed on the highlight.js download page.
medium contains some more frequently used languages.
large contains all languages available.

You could also download a custom version from the Highlight.js Download page and place only the highlight.pack.js file from the zipfile in the folder site/addons/Highlight/resources/js and rename it to (for example) site/addons/Highlight/resources/js/highlight.pack.custom.js. you could then configure it to use this version by defining custom as the library_version.

Usage

When codeblocks are used (1 tab or 4 spaces) Highlight.js tries to guess what code is used. (You can inspect the class on the generated <pre><code class="language-php"> … </code></pre> codeblock to see how it was interpreted.)
If the autodetection didn't work out correctly or you just want control over the rendering, just wrap the code in fenced codeblock and add the language. For example:


```php
$app->singleton(
    'Illuminate\Contracts\Http\Kernel',
    'Statamic\Http\Kernel'
);

$app->singleton(
    'Illuminate\Contracts\Console\Kernel',
    'Statamic\Console\Kernel'
);
```  

wich will render like this:

$app->singleton(
    'Illuminate\Contracts\Http\Kernel',
    'Statamic\Http\Kernel'
);

$app->singleton(
    'Illuminate\Contracts\Console\Kernel',
    'Statamic\Console\Kernel'
);

See for more information the Highlight.js documentation.