Muuntimet

Muuntimilla voit muokata korostettua tulostetta kaikissa vaiheissa — lähdemerkkijonosta tokenruudukon kautta lopulliseen HAST-puuhun ja HTML:iin. shikiphp siirtää Shiki-muunninmallin koukku koukulta, joten muuntimet toimivat samoin kuin niiden JavaScript-vastineet.

Välitä ne transformers-valinnan kautta:

use Shikiphp\Shikiphp;
use Shikiphp\Transformer\Notation\NotationHighlight;
use Shikiphp\Transformer\Notation\NotationDiff;

$code = <<<'JS'
console.log('this line is highlighted') // [!code highlight]
console.log('old line') // [!code --]
console.log('new line') // [!code ++]
JS;

echo Shikiphp::codeToHtml($code, [
    'lang'         => 'js',
    'theme'        => 'vitesse-dark',
    'transformers' => [
        new NotationHighlight(),
        new NotationDiff(),
    ],
]);

Käsittelyputki

Kukin muunnin on olio, joka toteuttaa Shikiphp\Transformer\Transformer-rajapinnan. Putki suorittaa koukut järjestyksessä yhden lohkon muodostamisen aikana:

Kaikki koukut ovat valinnaisia. Palautettu arvo korvaa syötteen; arvon null palauttaminen säilyttää sen ennallaan.

enforce() määrittää järjestyksen muuntimien välillä: 'pre' suoritetaan ensin, 'post' viimeisenä ja null (oletus) rekisteröintijärjestyksessä niiden välissä.

Muuntimen kirjoittaminen

Laajenna Shikiphp\Transformer\AbstractTransformer-luokkaa, jotta sinun tarvitsee korvata vain tarvitsemasi koukut; muut eivät tee mitään. Muuntimen konteksti tarjoaa addClassToHast()-funktion luokkien lisäämiseen elementteihin.

use Shikiphp\Hast\Element;
use Shikiphp\Shikiphp;
use Shikiphp\Transformer\AbstractTransformer;
use Shikiphp\Transformer\TransformerContext;

final class AddLanguageClass extends AbstractTransformer
{
    public function pre(Element $element, TransformerContext $context): ?Element
    {
        if ($context->lang !== null) {
            $context->addClassToHast($element, 'language-' . $context->lang);
        }

        return $element;
    }
}

echo Shikiphp::codeToHtml('const answer = 42', [
    'lang'         => 'js',
    'theme'        => 'nord',
    'transformers' => [new AddLanguageClass()],
]);
// <pre class="shiki nord language-js" …>

Valmiit muuntimet

Merkintämuuntimet

Nämä lukevat lähteen erityiset // [!code …]-kommentit (kommenttimerkintä havaitaan automaattisesti kielen mukaan) ja muuntavat ne luokiksi poistaen itse kommentin. Ne ovat suoria siirtoja @shikijs/transformers-merkintäjoukosta.

NotationHighlight

Shikiphp\Transformer\Notation\NotationHighlight — // [!code highlight] (tai // [!code hl]) lisää riville luokan highlighted.

console.log('kept plain')
console.log('this line is highlighted') // [!code highlight]

NotationDiff

Shikiphp\Transformer\Notation\NotationDiff — // [!code ++] merkitsee rivin lisätyksi (diff add), // [!code --] poistetuksi (diff remove).

console.log('old line') // [!code --]
console.log('new line') // [!code ++]

NotationFocus

Shikiphp\Transformer\Notation\NotationFocus — // [!code focus] lisää luokan focused.

console.log('focus on me') // [!code focus]

NotationErrorLevel

Shikiphp\Transformer\Notation\NotationErrorLevel — // [!code error], // [!code warning] ja // [!code info] lisäävät luokan highlighted sekä error / warning / info.

throwSomething() // [!code error]
maybeRisky()     // [!code warning]

NotationWordHighlight

Shikiphp\Transformer\Notation\NotationWordHighlight — // [!code word:foo] (valinnaisesti // [!code word:foo:2] rajaamaan vaikutus seuraaviin N riviin) ympäröi jokaisen foo-esiintymän span-elementillä, jossa on highlighted-word.

// [!code word:config]
const config = loadConfig()

Metamuuntimet

Nämä lukevat koodiaitausten kautta annetun metamerkkijonon meta-valinnasta (meta['__raw']), samalla tavoin kuin Shiki lukee koodiaitauksen kielen jälkeisen tekstin.

MetaHighlight

Shikiphp\Transformer\MetaHighlight — korostaa metavälillä nimettyjä rivejä, esimerkiksi {1,3-5}, ja lisää luokan highlighted.

use Shikiphp\Shikiphp;
use Shikiphp\Transformer\MetaHighlight;

$code = "const a = 1\nconst b = 2\nconst c = 3\nconst d = 4\nconst e = 5";

echo Shikiphp::codeToHtml($code, [
    'lang'         => 'js',
    'theme'        => 'nord',
    'meta'         => ['__raw' => '{1,3-5}'],
    'transformers' => [new MetaHighlight()],
]);

MetaWordHighlight

Shikiphp\Transformer\MetaWordHighlight — korostaa metamerkkijonossa /word/-syntaksilla nimettyjä sanoja ja lisää luokan highlighted-word.

Tyhjemerkit ja rakenne

RenderWhitespace

Shikiphp\Transformer\RenderWhitespace — ympäröi välilyönti- ja sarkainmerkit span-elementeillä (luokat ovat oletuksena space ja tab), jotta ne voidaan näyttää näkyvästi. Konstruktorille annetaan (classSpace, classTab, position), jossa position on 'all' (oletus), 'boundary', 'trailing' tai 'leading'.

CompactLineOptions

Shikiphp\Transformer\CompactLineOptions — lisää luokkia tietyille riveille {line, classes}-alkioiden luettelon perusteella.

use Shikiphp\Transformer\CompactLineOptions;

$transformer = new CompactLineOptions([
    ['line' => 1, 'classes' => 'highlighted'],
    ['line' => 3, 'classes' => ['highlighted', 'error']],
]);

Rivinumerointi alkaa numerosta 1. Välitä olio transformers-valinnassa kuten mikä tahansa muu muunnin.

RemoveNotationEscape

Shikiphp\Transformer\RemoveNotationEscape — poistaa suojauksen [\!code …]-muodosta, jolla kirjoitetaan kirjaimellinen merkintäkommentti käynnistämättä merkintämuunninta.

RemoveLineBreak

Shikiphp\Transformer\RemoveLineBreak — poistaa rivinvaihtotekstisolmut rivien välistä (Shiki-olion transformerRemoveLineBreak).

StyleToClass

Shikiphp\Transformer\StyleToClass — siirtää sisäiset tyylit luoduiksi luokiksi ja kerää tyylitiedoston, jonka haet komennolla getCSS(). Luokkien nimet tiivistävät tyylin Shiki-olion cyrb53-toiminnolla, joten tuloste on tavutasolla identtinen kohteen @shikijs/transformers 4.2.0 kanssa, myös sen rajauksen osalta:

• <pre>-tyyli muuttuu aina luokaksi.
• Tokenien span-elementit muunnetaan vain, jos niissä on valmiiksi luotu tyyli, kuten silloin, kun käytössä on themes-kartta. Yhdellä theme-teemalla tokenien span-elementit säilyttävät sisäisen style="color:…"-tyylinsä, kuten kohteessa Shiki.

use Shikiphp\Shikiphp;
use Shikiphp\Transformer\StyleToClass;

$code = 'const answer = 42';
$styleToClass = new StyleToClass();

$html = Shikiphp::codeToHtml($code, [
    'lang'         => 'js',
    'themes'       => ['light' => 'github-light', 'dark' => 'github-dark'],
    'transformers' => [$styleToClass],
]);

$css = $styleToClass->getCSS(); // collected stylesheet for the classes above

Konstruktorille annetaan (classPrefix, classSuffix, classReplacer); oletusetuliite on __shiki_.