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.
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.
You can install the package via composer:
composer require spatie/commonmark-shiki-highlighterIn 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.0or Yarn
yarn add shiki@^1.3.0Here'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()));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.
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";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.
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);
}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));Highlighting with Shiki is a resource intensive process. We highly recommend using some form of caching.
composer testPlease see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
If you don't want to install and handle Shiki yourself, take a look at Torchlight, which can highlight your code with minimal setup.
The MIT License (MIT). Please see License File for more information.