spatie / sidecar-shiki
Run Shiki highlighting with Sidecar
Installs: 10 206
Dependents: 0
Suggesters: 0
Security: 0
Stars: 35
Watchers: 4
Forks: 1
Open Issues: 0
Requires
- php: ^8.1
- hammerstone/sidecar: ^0.5|^0.6
- illuminate/contracts: ^9.0|^10.0|^11.0
- spatie/laravel-package-tools: ^1.9.2
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.8
- nunomaduro/collision: ^6.0
- nunomaduro/larastan: ^2.0.1
- orchestra/testbench: ^7.0|^8.0
- pestphp/pest: ^1.21
- pestphp/pest-plugin-laravel: ^1.1
- phpstan/extension-installer: ^1.1
- phpstan/phpstan-deprecation-rules: ^1.0
- phpstan/phpstan-phpunit: ^1.0
- phpunit/phpunit: ^9.5
- spatie/laravel-ray: ^1.26
- spatie/pest-plugin-snapshots: ^1.1
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"
Register the HighlightFunction::class
in your sidecar.php
config file.
/* * 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"><?</span><span style="color: #D8DEE9FF">php </span><span style="color: #81A1C1">echo</span><span style="color: #D8DEE9FF"> </span><span style="color: #ECEFF4">"</span><span style="color: #A3BE8C">Hello World</span><span style="color: #ECEFF4">"</span><span style="color: #81A1C1">;</span><span style="color: #D8DEE9FF"> </span><span style="color: #81A1C1">?></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.