Guida introduttiva

Installazione

composer require shikiphp/shikiphp

shikiphp richiede PHP 8.2 o versioni successive con ext-json e ext-mbstring, entrambi abilitati in quasi tutte le build PHP. Nient'altro: niente Node, nessun binding nativo Oniguruma e nessun'estensione aggiuntiva.

Il primo blocco

La facade statica Shikiphp è il modo più rapido per iniziare. Passate il codice, un id lingua e un id tema:

use Shikiphp\Shikiphp;

$html = Shikiphp::codeToHtml(<<<'PHP'
<?php
function greet(string $name): string {
    return "Hello, {$name}!";
}
PHP, [
    'lang'  => 'php',
    'theme' => 'github-dark',
]);

echo $html;

codeToHtml restituisce un blocco <pre class="shiki …"> completo e formattato. I colori di primo piano e di sfondo sono specificati in linea sull'<pre>, quindi il blocco viene visualizzato correttamente senza bisogno di fogli di stile aggiuntivi.

Temi chiaro e scuro

Invece di un singolo theme, passate una mappa themes. shikiphp genera variabili CSS (come Shiki), così un singolo blocco visualizzato si adatta alla modalità chiara e scura:

use Shikiphp\Shikiphp;

$code = 'const answer: number = 42';

echo Shikiphp::codeToHtml($code, [
    'lang'   => 'ts',
    'themes' => ['light' => 'github-light', 'dark' => 'github-dark'],
]);

Per impostazione predefinita, i colori del tema light sono quelli in linea e dark viene esposto tramite variabili --shiki-dark. Attivate il tema scuro con una piccola quantità di CSS: lo stesso frammento di codice Shiki documenta:

html.dark .shiki,
html.dark .shiki span {
  color: var(--shiki-dark) !important;
  background-color: var(--shiki-dark-bg) !important;
  /* and font styles */
  font-style: var(--shiki-dark-font-style) !important;
  font-weight: var(--shiki-dark-font-weight) !important;
  text-decoration: var(--shiki-dark-text-decoration) !important;
}

Potete scegliere quale tema usare come predefinito in linea con l'opzione defaultColor oppure impostare defaultColor: false per generare solo variabili.

Id di lingua e alias

Le lingue sono indicate dal loro id Shiki o da un alias: php, ts, js, rust, python, html e così via. Consultate Lingue per sapere come elencare tutto ciò che è incluso, e Temi per gli id dei temi.

Riutilizzare l'evidenziatore

La facade crea e memorizza nella cache in modo differito un Highlighter incluso, quindi le chiamate ripetute a Shikiphp::codeToHtml riutilizzano le stesse cache di grammatiche e temi. Se vi serve l'API più completo (output HAST, grammatiche personalizzate, griglie di token), recuperate direttamente l'istanza:

use Shikiphp\Shikiphp;

$code = 'fn main() {}';

$highlighter = Shikiphp::highlighter();
$hast = $highlighter->codeToHast($code, ['lang' => 'rust', 'theme' => 'nord']);

Consultate la API per la documentazione completa.