README

使用 Sidecar 运行 Shiki 突出显示

Shiki 是一个美丽的语法高亮器，由许多代码编辑器使用的相同语言引擎提供支持。这个包允许您通过 Sidecar 在 AWS Lambda 上运行 Shiki。

您不需要在服务器上安装 Node 或 Shiki 的任何依赖项。

支持我们

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

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

要求

此包要求在您的 Laravel 应用程序中安装了 hammerstone/sidecar。

按照 Sidecar 安装和配置说明进行。

安装

您可以通过 composer 安装此包。

composer require spatie/sidecar-shiki

可选地，您可以使用以下命令发布配置文件：

php artisan vendor:publish --tag="sidecar-shiki-config"

在您的 sidecar.php 配置文件中注册 HighlightFunction::class。

/*
 * All of your function classes that you'd like to deploy go here.
 */
'functions' => [
    \Spatie\SidecarShiki\Functions\HighlightFunction::class,
],

通过运行以下命令部署 Lambda 函数：

php artisan sidecar:deploy --activate

有关详细信息，请参阅 Sidecar 文档。

用法

您可以通过调用 \Spatie\SidecarShiki\SidecarShiki::highlight() 函数来突出显示代码。

use Spatie\SidecarShiki\SidecarShiki;

SidecarShiki::highlight(
    code: '<?php echo "Hello World"; ?>',
    language: 'php',
    theme: 'github-light',
);

输出是通过 AWS Lambda 渲染的以下 HTML 块，将在浏览器中完美输出

<pre class="shiki" style="background-color: #2e3440ff"><code><span class="line"><span style="color: #81A1C1">&lt;?</span><span style="color: #D8DEE9FF">php </span><span style="color: #81A1C1">echo</span><span style="color: #D8DEE9FF"> </span><span style="color: #ECEFF4">&quot;</span><span style="color: #A3BE8C">Hello World</span><span style="color: #ECEFF4">&quot;</span><span style="color: #81A1C1">;</span><span style="color: #D8DEE9FF"> </span><span style="color: #81A1C1">?&gt;</span></span></code></pre>

标记行作为突出显示、添加、删除或聚焦

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],
);

然后您可以在自己的 CSS 中针对这些类来为这些行着色。

使用 Commonmark HighlightCodeExtension

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

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

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

测试

测试套件会连接到 AWS 并运行已部署的 Lambda 函数。为了运行测试套件，您需要一个活动的 AWS 账户。

我们可以使用本地的 sidecar:configure artisan 命令为 Sidecar 创建必要的 AWS 凭据。首先将 testbench.example.yaml 文件复制到 testbench.yaml。然后运行 ./vendor/bin/testbench sidecar:configure 以开始 Sidecar 设置过程。（您只需设置一次）

cp testbench.yaml.example testbench.yaml
cp .env.example .env
./vendor/bin/testbench sidecar:configure

完成 Sidecar 设置过程后，您将收到几个 SIDECAR_* 环境变量。将这些凭据添加到 .env 和 testbench.yaml 文件中。

现在我们可以将本地的 HighlightFunction 部署到 AWS Lambda。在执行测试套件之前，在您的终端中运行以下命令。

./vendor/bin/testbench sidecar-shiki:setup

部署成功后，您可以运行测试套件。

composer test

更新日志

请参阅更新日志，了解最近有哪些变化。

贡献

请参阅贡献指南以获取详细信息。

安全漏洞

请查阅我们的安全策略了解如何报告安全漏洞。

致谢

特别感谢 Stefan Zweifel，他的 sidecar-browsershot 包在测试此功能方面给予了巨大帮助。

替代方案

如果您不想自行安装和处理 Shiki，请查看 Torchlight，它可以最小化设置来突出显示您的代码。

许可协议

MIT 许可协议 (MIT)。请参阅许可文件以获取更多信息。

spatie / sidecar-shiki

维护者

详细信息