Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/spatie/sidecar-shiki
Run Shiki highlighting with Sidecar
https://github.com/spatie/sidecar-shiki
aws-lambda highlighting shiki sidecar
Last synced: 3 days ago
JSON representation
Run Shiki highlighting with Sidecar
- Host: GitHub
- URL: https://github.com/spatie/sidecar-shiki
- Owner: spatie
- License: mit
- Created: 2022-06-24T17:28:57.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-23T08:04:25.000Z (3 months ago)
- Last Synced: 2024-12-24T04:20:50.372Z (10 days ago)
- Topics: aws-lambda, highlighting, shiki, sidecar
- Language: PHP
- Homepage: https://spatie.be/open-source
- Size: 2.58 MB
- Stars: 35
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
[
](https://supportukrainenow.org)
# Run Shiki highlighting with Sidecar
[](https://packagist.org/packages/spatie/sidecar-shiki)
[](https://github.com/spatie/sidecar-shiki/actions?query=workflow%3Arun-tests+branch%3Amain)
[](https://github.com/spatie/sidecar-shiki/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain)
[](https://packagist.org/packages/spatie/sidecar-shiki)
[Shiki](https://github.com/shikijs/shiki) is a beautiful syntax highlighter powered by the same language engine that many code editors use. This package allows you to run [Shiki](https://github.com/shikijs/shiki) on AWS Lambda through [Sidecar](https://github.com/hammerstonedev/sidecar).
You won't need to install Node, or any of Shiki's dependencies, on your server.
## Support us
[
](https://spatie.be/github-ad-click/sidecar-shiki)
We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
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](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
## Requirements
This package requires that `hammerstone/sidecar` has been installed in your Laravel application.
Follow the [Sidecar installation](https://hammerstone.dev/sidecar/docs/main/installation) and [configuration](https://hammerstone.dev/sidecar/docs/main/configuration) instructions.
## Installation
You can install the package via composer:
```bash
composer require spatie/sidecar-shiki
```
Optionally, you can publish the config file with:
```bash
php artisan vendor:publish --tag="sidecar-shiki-config"
```
Register the `HighlightFunction::class` in your `sidecar.php` config file.
```php
/*
* 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:
```shell
php artisan sidecar:deploy --activate
```
See [Sidecar documentation](https://hammerstone.dev/sidecar/docs/main/functions/deploying) for details.
## Usage
You can highlight code by calling the `\Spatie\SidecarShiki\SidecarShiki::highlight()` function.
```php
use Spatie\SidecarShiki\SidecarShiki;
SidecarShiki::highlight(
code: '',
language: 'php',
theme: 'github-light',
);
```
The output is this chunk of HTML rendered through AWS Lambda which will output beautifully in the browser:
```html
<?php echo "Hello World"; ?>
```
### Marking lines as highlighted, added, deleted or focus
```php
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](https://github.com/shikijs/shiki/blob/master/docs/themes.md) that Shiki supports.
```php
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](https://aws.amazon.com/).
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)
```shell
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.
```shell
./vendor/bin/testbench sidecar-shiki:setup
```
After the successful deployment, you can run the testsuite.
```bash
composer test
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
- [Rias Van der Veken](https://github.com/riasvdv)
- [All Contributors](../../contributors)
Special thanks to [Stefan Zweifel]() for his [sidecar-browsershot](https://github.com/stefanzweifel/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](https://torchlight.dev), which can highlight your code with minimal setup.
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.