Guida alla configurazione dell’evidenziazione del codice per Gutenberg e Prism.js

Il blocco “Codice” predefinito di Gutenberg non supporta l’evidenziazione della sintassi. La libreria Prism.js risolve questo problema. Questa guida descrive come configurare Prism.js, includendo una soluzione automatica per i problemi di visualizzazione dei caratteri HTML < e >.

Il problema: Conflitto con i tag HTML

Un browser interpreta i caratteri < e > all’interno dei blocchi di codice come tag HTML, il che rompe il layout della pagina.

La soluzione: Escape dei caratteri

Per una visualizzazione corretta, i caratteri speciali devono essere sostituiti con entità HTML:

• < viene sostituito con <
• > viene sostituito con >

Questo processo viene automatizzato utilizzando un filtro di WordPress per evitare la sostituzione manuale e problemi con l’editor di Gutenberg.

Configurazione passo dopo passo

Passo 0: Preparare un tema figlio

Tutte le modifiche devono essere apportate in un tema figlio (child theme) per garantire che non vengano eliminate durante l’aggiornamento del tema principale.

---

Passo 1: Scaricare e configurare una build di Prism.js

1. Vai al sito web: prismjs.com/download.html.
2. Seleziona i componenti:
   • Livello di compressione (Compression level): Minified.
   • Linguaggi (Languages): Markup, CSS, C-like, JavaScript. Aggiungi qualsiasi altro linguaggio richiesto.
   • Plugin: Line Numbers, Toolbar, Copy to Clipboard Button.
3. Scarica i file: Fai clic su DOWNLOAD JS e DOWNLOAD CSS.

Posiziona i file prism.js e prism.css scaricati nella cartella principale del tuo tema figlio.

---

Passo 2: Includere i file in functions.php

Per includere i file in WordPress, apri il file functions.php del tuo tema figlio e aggiungi il seguente codice:

<?php

/**
 * Includi stili e script per l'evidenziazione del codice.
 */
add_action('wp_enqueue_scripts', 'theme_enqueue_prism_assets');
function theme_enqueue_prism_assets() {
    // Includi gli stili di Prism
    wp_enqueue_style(
        'prism-css',
        get_stylesheet_directory_uri() . '/prism.css',
        array(),
        '1.29.0' // Versione per il controllo della cache
    );

    // Includi lo script di Prism
    wp_enqueue_script(
        'prism-js',
        get_stylesheet_directory_uri() . '/prism.js',
        array(),
        '1.29.0',
        true // Carica nel footer
    );
}

/**
 * Aggiungi automaticamente classi ai blocchi di codice di Gutenberg.
 */
add_filter('render_block_core/code', 'theme_add_prism_classes_to_code_block', 10, 2);
function theme_add_prism_classes_to_code_block($block_content, $block) {
    // Aggiungi la classe line-numbers al tag <pre>
    $block_content = str_replace('<pre class="wp-block-code">', '<pre class="wp-block-code line-numbers">', $block_content);
    return $block_content;
}

Questo codice include i file e attiva la numerazione delle righe.

---

Passo 3: Eseguire l’escape automatico dei caratteri

Il passo chiave è aggiungere un filtro in functions.php per eseguire l’escape automatico dei caratteri speciali prima di salvare l’articolo.

/**
 * Esegui l'escape dei caratteri HTML all'interno dei tag <code> al salvataggio di un articolo.
 */
add_filter('content_save_pre', 'theme_escape_code_on_save');
function theme_escape_code_on_save($content) {
    // Trova tutti i blocchi <code>...
    return preg_replace_callback('/(.*?)<\/code>/is', function($matches) {
        $attributes = $matches[1]; // Attributi del tag
        $code_content = $matches[2]; // Contenuto del tag

        // Esegui l'escape del contenuto
        $escaped_content = htmlspecialchars($code_content, ENT_NOQUOTES, 'UTF-8');

        // Riassembla il tag
        return '<code' . $attributes . '>' . $escaped_content . '';
    }, $content);
}

L’hook content_save_pre si attiva prima di scrivere sul database. La funzione htmlspecialchars converte i caratteri speciali in entità HTML sicure.

---

Passo 4: Stile in style.css

Per una presentazione pulita, aggiungi i seguenti stili al file style.css del tuo tema figlio:

/* Stili per i blocchi di codice */
pre[class*="language-"] {
    border-radius: 5px;
    border: 1px solid #ddd;
    font-size: 14px;
    box-shadow: 0 1px 2px rgba(0,0,0,0.05);
}

/* Stili per la barra degli strumenti di Prism */
div.code-toolbar {
    position: relative;
}

div.code-toolbar > .toolbar {
    position: absolute;
    top: 10px;
    right: 10px;
    opacity: 0;
    transition: opacity 0.3s ease-in-out;
}

div.code-toolbar:hover > .toolbar {
    opacity: 1; /* Mostra il pulsante al passaggio del mouse */
}

.toolbar-item button {
    padding: 5px 10px;
    background: #f5f5f5;
    color: #333;
    border: 1px solid #ddd;
    border-radius: 3px;
    font-size: 13px;
    cursor: pointer;
}

.toolbar-item button:hover {
    background-color: #e0e0e0;
}

Risultato

Dopo aver completato questi passaggi, ogni blocco di codice in Gutenberg avrà:

• Evidenziazione automatica della sintassi.
• Numeri di riga.
• Un pulsante per copiare.
• Rendering corretto dei tag HTML senza rompere il layout.