Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/spatie/commonmark-shiki-highlighter
Highlight code blocks with league/commonmark and Shiki
https://github.com/spatie/commonmark-shiki-highlighter
commonmark php syntax-highlighting
Last synced: 3 days ago
JSON representation
Highlight code blocks with league/commonmark and Shiki
- Host: GitHub
- URL: https://github.com/spatie/commonmark-shiki-highlighter
- Owner: spatie
- License: mit
- Created: 2021-07-08T20:50:20.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-12T09:37:15.000Z (about 1 month ago)
- Last Synced: 2024-12-15T07:02:31.876Z (10 days ago)
- Topics: commonmark, php, syntax-highlighting
- Language: PHP
- Homepage: https://freek.dev/2024-how-to-render-markdown-with-perfectly-highlighted-code-snippets
- Size: 85 KB
- Stars: 79
- Watchers: 4
- Forks: 14
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Highlight code blocks with league/commonmark and Shiki
[](https://packagist.org/packages/spatie/commonmark-shiki-highlighter)
[](https://github.com/spatie/commonmark-shiki-highlighter/actions/workflows/run-tests.yml)
[](https://github.com/spatie/commonmark-shiki-highlighter/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amaster)
[](https://packagist.org/packages/spatie/commonmark-shiki-highlighter)
This package contains a block renderer for [league/commonmark](https://github.com/thephpleague/commonmark) to highlight code blocks using [Shiki PHP](https://github.com/spatie/shiki-php).
This package also ships with the following extra languages, on top of the [100+ that Shiki supports](https://github.com/shikijs/shiki/tree/master/docs/languages.md) out of the box:
- Antlers
- Blade
If you're using Laravel, make sure to look at our [spatie/laravel-markdown](https://github.com/spatie/laravel-markdown) package which offers easy integration with Shiki in laravel projects.
## Support us
[
](https://spatie.be/github-ad-click/commonmark-shiki-highlighter)
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).
## Installation
You can install the package via composer:
```bash
composer require spatie/commonmark-shiki-highlighter
```
In your project, you must have v1 of the JavaScript package [`shiki`](https://github.com/shikijs/shiki) installed, otherwise the `
` element will not be present in the output.
You can install it via npm
```bash
npm install shiki@^1.3.0
```
or Yarn
```bash
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.
```php
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`:
```php
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](https://github.com/shikijs/shiki/blob/master/docs/themes.md) that Shiki supports.
Alternatively, you can use a custom theme. Shiki [supports](https://github.com/shikijs/shiki/blob/master/docs/themes.md) any [VSCode themes](https://code.visualstudio.com/docs/getstarted/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.
```md
```php{1,2}{3}
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
```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
- [Freek Van der Herten](https://github.com/freekmurze)
- [All Contributors](../../contributors)
## 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.