Teisendajad

Teisendajad võimaldavad esiletõstetud väljundit igas etapis kujundada — alates algsest lähtekoodistringist läbi märgendite ruudustiku kuni lõpliku HAST-puu ja HTML-ni. shikiphp järgib Shiki teisendajate mudelit konks konksu haaval, nii et teisendajad toimivad samamoodi nagu nende JavaScript vasted.

Anna need edasi valikuga transformers:

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

Töötlusahel

Iga teisendaja on objekt, mis rakendab liidest Shikiphp\Transformer\Transformer. Torujuhe käivitab konksud järjest ühe ploki koostamisel:

Kõik konksud on valikulised. Väärtuse tagastamine asendab sisendi; null tagastamine jätab selle muutmata.

enforce() juhib teisendajate järjestust: 'pre' käivitatakse esimesena, 'post' viimasena ja null (vaikeväärtus) nende vahel registreerimise järjekorras.

Teisendaja kirjutamine

Laienda Shikiphp\Transformer\AbstractTransformer, et peaksid üle kirjutama ainult vajalikud konksud; ülejäänud ei tee midagi. Teisendaja kontekstis on addClassToHast(), millega elementidele klasse lisada.

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" …>

Sisseehitatud teisendajad

Märgistus teisendajad

Need loevad lähtekoodi erilisi // [!code …] kommentaare (kommentaari süntaks tuvastatakse automaatselt) ja teisendavad need klassideks, eemaldades kommentaari enda. Need on @shikijs/transformers märgistuskomplekti otsesed teisendused.

NotationHighlight

Shikiphp\Transformer\Notation\NotationHighlight — // [!code highlight] (või // [!code hl]) lisab reale klassi highlighted.

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

NotationDiff

Shikiphp\Transformer\Notation\NotationDiff — // [!code ++] märgib rea lisatuks (diff add) ja // [!code --] eemaldatuks (diff remove).

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

NotationFocus

Shikiphp\Transformer\Notation\NotationFocus — // [!code focus] lisab klassi focused.

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

NotationErrorLevel

Shikiphp\Transformer\Notation\NotationErrorLevel — // [!code error], // [!code warning] ja // [!code info] lisavad klassi highlighted ning error / warning / info.

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

NotationWordHighlight

Shikiphp\Transformer\Notation\NotationWordHighlight — // [!code word:foo] (valikuliselt // [!code word:foo:2], et piirata mõju järgmise N reaga) ümbritseb iga foo esinemiskorra späniga, millel on highlighted-word.

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

Meta teisendajad

Need loevad koodipiirde meta-stringi, mis antakse edasi valikuga meta (meta['__raw']); samamoodi loeb Shiki tarastatud koodiploki keele järel olevat teksti.

MetaHighlight

Shikiphp\Transformer\MetaHighlight — tõstab esile meta-vahemikus nimetatud read, näiteks {1,3-5}, lisades klassi 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 — tõstab metastringis nimetatud sõnad esile süntaksiga /word/, lisades highlighted-word.

Tühimärgid ja struktuur

RenderWhitespace

Shikiphp\Transformer\RenderWhitespace — ümbritseb tühiku- ja tabeldusmärke spännidega (vaikeklassid space ja tab), et neid saaks nähtavalt kuvada. Konstruktorile antakse (classSpace, classTab, position), kus position on 'all' (vaikeväärtus), 'boundary', 'trailing' või 'leading'.

CompactLineOptions

Shikiphp\Transformer\CompactLineOptions — rakendab kindlatele ridadele klasse {line, classes} kirjete loendist.

use Shikiphp\Transformer\CompactLineOptions;

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

Reanumbrid algavad ühest. Anna objekt edasi valikuga transformers, nagu iga teisendaja puhul.

RemoveNotationEscape

Shikiphp\Transformer\RemoveNotationEscape — eemaldab paomärgid vormilt [\!code …], mida kasutatakse sõnasõnalise märgistuskommentaari kirjutamiseks ilma märgistuse teisendajat käivitamata.

RemoveLineBreak

Shikiphp\Transformer\RemoveLineBreak — eemaldab ridade vahelt reavahetuse tekstisõlmed (Shiki omad transformerRemoveLineBreak).

StyleToClass

Shikiphp\Transformer\StyleToClass — viib tekstisisesed stiilid genereeritud klassidesse ja kogub laaditabeli, mille saad kätte funktsiooniga getCSS(). Klasside nimed räsitakse stiili ja Shiki elemendi cyrb53 põhjal, nii et väljund on bait-baidilt identne elemendi @shikijs/transformers 4.2.0-iga, sealhulgas selle skoobiga:

• <pre> stiil muutub alati klassiks.
• Märgendite spännid teisendatakse ainult siis, kui neil on eelehitatud stiil, nagu themes kaardi puhul. Ühe theme korral säilitavad märgendite spännid tekstisisese style="color:…", nagu Shiki puhul.

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

Konstruktori argument on (classPrefix, classSuffix, classReplacer); eesliite vaikeväärtus on __shiki_.