README

This package contains a block renderer for league/commonmark to highlight code blocks using Shiki PHP.

This package also ships with the following extra languages, on top of the 100+ that Shiki supports out of the box:

Antlers
Blade

If you're using Laravel, make sure to look at our spatie/laravel-markdown package which offers easy integration with Shiki in laravel projects.

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.

Installation

You can install the package via composer:

composer require spatie/commonmark-shiki-highlighter

In your project, you must have v1 of the JavaScript package shiki installed, otherwise the <pre> element will not be present in the output.

You can install it via npm

npm install shiki@^1.3.0

or Yarn

yarn add shiki@^1.3.0

Usage

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

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\MarkdownConverter;
use Spatie\CommonMarkShikiHighlighter\HighlightCodeExtension;

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

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

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

Alternatively, you can inject an already instantiated Shiki instance into the HighlightCodeExtension:

use Spatie\ShikiPhp\Shiki;
use Spatie\CommonMarkShikiHighlighter\HighlightCodeExtension;

$environment->addExtension(new HighlightCodeExtension(shiki: new Shiki()));

Using themes

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

Alternatively, you can use a custom theme. Shiki supports any VSCode themes. You can load a theme simply by passing an absolute path of a theme file to the $theme argument.

Marking lines as highlighted, added, deleted and focus

You can mark lines using the Markdown info tag as highlighted or focused. You can prefix lines with + or - to mark them as added or deleted. In the first pair of brackets, you can specify line numbers that should be highlighted. In an optional second pair you can specify which lines should be focused on.

```php{1,2}{3}
<?php
echo "We're highlighting line 1 and 2";
echo "And focusing line 3";

```php
<?php
+ echo "This line is marked as added";
- echo "This line is marked as deleted";

More syntax examples for highlighting & focusing

Line numbers start at 1.

```php - Don't highlight any lines

```php{4} - Highlight just line 4
```php{4-6} - Highlight the range of lines from 4 to 6 (inclusive)
```php{1,5} - Highlight just lines 1 and 5 on their own
```php{1-3,5} - Highlight 1 through 3 and then 5 on its own
```php{5,7,2-3} - The order of lines don't matter. However, specifying 3-2 will not work.

```php{}{4} - Focus just line 4
```php{}{4-6} - Focus the range of lines from 4 to 6 (inclusive)
```php{}{1,5} - Focus just lines 1 and 5 on their own
```php{}{1-3,5} - Focus 1 through 3 and then 5 on its own
```php{}{5,7,2-3} - The order of lines don't matter. However, specifying 3-2 will not work.

Styling highlighted lines

When you mark lines as highlighted, added, deleted or focused, Shiki will apply some classes to those lines. You should add some CSS to your page to style those lines. Here's a bit of example CSS to get you started.

.shiki .highlight {
    background-color: hsl(197, 88%, 94%);
    padding: 3px 0;
}

.shiki .add {
    background-color: hsl(136, 100%, 96%);
    padding: 3px 0;
}

.shiki .del {
    background-color: hsl(354, 100%, 96%);
    padding: 3px 0;
}

.shiki.focus .line:not(.focus) {
    transition: all 250ms;
    filter: blur(2px);
}

.shiki.focus:hover .line {
    transition: all 250ms;
    filter: blur(0);
}

Throwing on exceptions

By default, the Shiki highlighter will not throw when something goes wrong and just return the non-highlighted code. If you want to throw the exception anyway, instantiate the highlighter with throw as true:

$environment = (new Environment())
    ->addExtension(new CommonMarkCoreExtension())
    ->addExtension(new HighlightCodeExtension(theme: $theme, throw: true));

A word on performance

Highlighting with Shiki is a resource intensive process. We highly recommend using some form of caching.

Testing

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

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 / commonmark-shiki-highlighter

Maintainers

Details