Highlighting code using Sidecar & Shiki

June 27th, 2022

Shiki is a beautiful syntax highlighter powered by the same language engine that many code editors use. We've just released a package that 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.

Introducing sidecar-shiki

We previously released shiki-php which is a way to highlight your code using Shiki, the difficult part with this package however is that you still need to install Node and Shiki.js on your server. In addition to this, Shiki is also a fairly resource intensive process which can really tax your server when you have a lot of highlighting to do.

Sidecar is a marvellous solution to this, as we can offload the Shiki process to AWS Lambda, we've also written the Lambda function in a way that keeps the most process intensive parts of Shiki (loading the languages & themes) in memory between warm executions so any highlighting gets done very quickly.

Check out sidecar-shiki

Installation

You'll first need to follow the Sidecar installation and configuration instructions. Once they're set up, you can add the HighlightFunction::class to the Sidecar configuration file

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

Then you can deploy the Lambda:

php artisan sidecar:deploy --activate

Usage

Once Sidecar and the Lambda are set up, using the package is just as easy as our shiki-php package

use Spatie\SidecarShiki\SidecarShiki;

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

The highlight method will call to the Lambda function and return the highlighted code, all functionality like languages, themes and highlighting lines are available and supported.

CommonMark extension

The sidecar-shiki package also comes with a CommonMark highlighting extension that can highlight fenced code blocks in your markdown.

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);
}

In closing

We're very exited about Sidecar and this new sidecar-shiki package. We're already using it on spatie.be for all of our documentation code snippets, we were using shiki-php before this but it had a tendency to take down our server when we needed to import all the documentation at the same time.

Of course, sidecar-shiki isn't the first package that our team has built. On our company website, check out all our open source packages in this long list. If you want to support us, consider picking up any of our paid products.

MENU