README

Run Shiki highlighting with Sidecar

Shiki is a beautiful syntax highlighter powered by the same language engine that many code editors use. This package allows you to run Shiki on AWS Lambda through Sidecar.

You won't need to install Node, or any of Shiki's dependencies, on your server.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Requirements

This package requires that hammerstone/sidecar has been installed in your Laravel application.

Follow the Sidecar installation and configuration instructions.

Installation

You can install the package via composer:

composer require spatie/sidecar-shiki

Optionally, you can publish the config file with:

php artisan vendor:publish --tag="sidecar-shiki-config"

/*
 * All of your function classes that you'd like to deploy go here.
 */
'functions' => [
    \Spatie\SidecarShiki\Functions\HighlightFunction::class,
],

Deploy the Lambda function by running:

php artisan sidecar:deploy --activate

See Sidecar documentation for details.

Usage

You can highlight code by calling the \Spatie\SidecarShiki\SidecarShiki::highlight() function.

use Spatie\SidecarShiki\SidecarShiki;

SidecarShiki::highlight(
    code: '<?php echo "Hello World"; ?>',
    language: 'php',
    theme: 'github-light',
);

The output is this chunk of HTML rendered through AWS Lambda which will output beautifully in the browser:

<pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">&lt;?</span><span style="color: #D8DEE9FF">php </span><span style="color: #81A1C1">echo</span><span style="color: #D8DEE9FF"> </span><span style="color: #ECEFF4">&quot;</span><span style="color: #A3BE8C">Hello World</span><span style="color: #ECEFF4">&quot;</span><span style="color: #81A1C1">;</span><span style="color: #D8DEE9FF"> </span><span style="color: #81A1C1">?&gt;</span></span></code></pre>

Marking lines as highlighted, added, deleted or focus

use Spatie\SidecarShiki\SidecarShiki;

// Highlighting lines 1 and 4,5,6
SidecarShiki::highlight(
    code: $code,
    language: 'php',
    highlightLines: [1, '4-6'],
);

// Marking line 1 as added
SidecarShiki::highlight(
    code: $code,
    language: 'php',
    addLines: [1],
);

// Marking line 1 as deleted
SidecarShiki::highlight(
    code: $code,
    language: 'php',
    deleteLines: [1],
);

// Marking line 1 as focus
SidecarShiki::highlight(
    code: $code,
    language: 'php',
    focusLines: [1],
);

You can then target these classes in your own CSS to color these lines how you want.

Using the Commonmark HighlightCodeExtension

Here's how we can create a function that can convert markdown to HTML with all code snippets highlighted. Inside the function we'll create a new MarkdownConverter that uses the HighlightCodeExtension provided by this package.

The $theme argument on HighlightCodeExtension expects the name of one of the many themes that Shiki supports.

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\MarkdownConverter;
use Spatie\SidecarShiki\Commonmark\HighlightCodeExtension;

function convertToHtml(string $markdown, string $theme): string
{
    $environment = (new Environment())
        ->addExtension(new CommonMarkCoreExtension())
        ->addExtension(new HighlightCodeExtension($theme));

    $markdownConverter = new MarkdownConverter(environment: $environment);

    return $markdownConverter->convertToHtml($markdown);
}

Testing

The testsuite makes connections to AWS and runs the deployed Lambda function. In order to run the testsuite, you will need an active AWS account.

We can use the native sidecar:configure artisan command to create the necessary AWS credentials for Sidecar. First copy the testbench.example.yaml file to testbench.yaml. Then run ./vendor/bin/testbench sidecar:configure to start the Sidecar setup process. (You only have to do the setup once)

cp testbench.yaml.example testbench.yaml
cp .env.example .env
./vendor/bin/testbench sidecar:configure

After finishing the Sidecar setup process, you will have received a couple of SIDECAR_* environment variables. Add these credentials to both .env and testbench.yaml.

Now we can deploy our local HighlightFunction to AWS Lambda. Run the following command in your terminal, before executing the testsuite.

./vendor/bin/testbench sidecar-shiki:setup

After the successful deployment, you can run the testsuite.

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

Special thanks to Stefan Zweifel for his sidecar-browsershot package as a big help in how to test this.

Alternatives

If you don't want to install and handle Shiki yourself, take a look at Torchlight, which can highlight your code with minimal setup.

License

The MIT License (MIT). Please see License File for more information.

spatie / sidecar-shiki

Maintainers

Details