README

此包包含一个用于 league/commonmark 的块渲染器，以使用 Shiki PHP 突出显示代码块。

此外，此包还提供了以下额外语言，除开 Shiki 默认支持的 100 多种语言

Antlers
Blade

如果你正在使用 Laravel，请确保查看我们的 spatie/laravel-markdown 包，它提供了在 Laravel 项目中与 Shiki 的简单集成。

支持我们

我们投入了大量资源来创建一流的开放源代码包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡给我们寄来明信片，说明您正在使用我们的哪个包。您可以在我们的联系页面找到我们的地址。我们将所有收到的明信片发布在我们的虚拟明信片墙上。

安装

您可以通过 composer 安装此包

composer require spatie/commonmark-shiki-highlighter

在您的项目中，您必须安装 JavaScript 包 shiki 的 v1 版本，否则输出中不会存在 <pre> 元素。

您也可以通过 npm 安装它

npm install shiki@^1.3.0

或 Yarn

yarn add shiki@^1.3.0

用法

以下是如何创建一个可以将 markdown 转换为带有所有代码片段突出显示的 HTML 的函数的方法。在函数内部将创建一个新的 MarkdownConverter，它使用此包提供的 HighlightCodeExtension。

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);
}

或者，您可以将已经实例化的 Shiki 实例注入到 HighlightCodeExtension 中

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

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

使用主题

在 HighlightCodeExtension 上，$theme 参数期望的是 Shiki 支持的许多主题之一。

或者，您可以使用自定义主题。Shiki 支持任何 VSCode 主题。您可以通过将主题文件的绝对路径传递给 $theme 参数来加载一个主题。

标记行以突出显示、添加、删除和聚焦

您可以使用 Markdown info 标记来标记行以突出显示或聚焦。您可以使用 + 或 - 前缀来标记行以添加或删除。在第一个括号对中，您可以指定应突出显示的行号。在可选的第二个括号中，您可以指定应聚焦的行。

```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";

突出显示和聚焦的更多语法示例

行号从 1 开始。

```php - 不要高亮任何行

```php{4} - 仅高亮第4行
```php{4-6} - 高亮第4到6行（包含）
```php{1,5} - 仅高亮第1和第5行
```php{1-3,5} - 高亮1到3行，然后单独高亮第5行
```php{5,7,2-3} - 行的顺序不重要。但是指定3-2将不会工作。

```php{}{4} - 仅聚焦第4行
```php{}{4-6} - 聚焦第4到6行（包含）
```php{}{1,5} - 仅聚焦第1和第5行
```php{}{1-3,5} - 聚焦1到3行，然后单独聚焦第5行
```php{}{5,7,2-3} - 行的顺序不重要。但是指定3-2将不会工作。

高亮行的样式

当你标记行作为高亮、添加、删除或聚焦时，Shiki会应用一些类到这些行上。你应该在你的页面上添加一些CSS来样式化这些行。以下是一段示例CSS以供开始。

.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);
}

抛出异常

默认情况下，Shiki高亮器在出错时不会抛出异常，而是返回未高亮的代码。如果你想无论如何都抛出异常，请使用throw作为true实例化高亮器。

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

关于性能的说明

使用Shiki进行高亮是一个资源密集型过程。我们强烈建议使用某种形式的缓存。

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

有关如何报告安全漏洞，请参阅我们的安全策略。

鸣谢

替代方案

如果你不想自己安装和处理Shiki，请查看Torchlight，它可以在最少设置的情况下高亮你的代码。

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。

spatie / commonmark-shiki-highlighter

维护者

详细信息