Quando lavori con Grav CMS da diversi anni, accumuli una serie di snippet che ti accompagnano da un progetto all'altro. Frontmatter YAML, template Twig, configurazioni per il syntax highlighting, pattern regex per Atom: scavare nella documentazione o in un vecchio repository ogni volta è tempo perso. Soprattutto quando Grav gira su un VPS e devi ricordare come installare correttamente il driver sqlite per PHP 8.3 o commentare SetHandler dopo un aggiornamento di Apache.

Questo cheat sheet è una distillazione dalla pratica reale: header predefinito, impostazioni Markdown per le pagine, snippet Twig nel corpo del post, regex per Atom per il post-processing dei file.md esportati e comandi per server Ubuntu. Tutto in un unico posto, con spiegazioni sul cosa e sul perché.

💡 Panoramica rapida:

• Configurare il frontmatter YAML di Grav con tutti i campi: taxonomy, page-toc, highlight, process, page-addon personalizzato
• Impostare la logica Markdown negli header di pagina: title, description, date, taxonomies, template
• Aggiungere codice Twig nel corpo: indice automatico tramite toc(), galleria Unitegallery
• Elaborare le esportazioni.md di Writage in Atom: sostituire media/ nei percorsi, passare classi per il lazy load
• Predisporre l'ambiente server: SQLite, Memcached, PHP 8.3 su Ubuntu 24.04, modifica di php*.conf per Virtualmin

Header predefinito di Grav per tutte le pagine del sito

Il frontmatter YAML di base di una pagina Grav include campi che il CMS legge durante il rendering. Di seguito un modello funzionante che copre la maggior parte delle attività tipiche: dalle tassonomie ai flag personalizzati page-addon.

1
title: ''
2
date: '2026-06-14 10:00'
3
published: true
4
media_order: poster.jpg
5
metadata:
6
    description: ''
7
taxonomy:
8
    category:
9
    - WordPress
10
    tag:
11
    - WordPress - Plugins
12
    - WordPress - Admin
13
page-toc:
14
    active: true
15
template: blog_item
16
highlight:
17
    enabled: true
18
    lines: true
19
page-addon:
20
    ifarmelazy: true

page-toc.active: true attiva il plugin Page Toc (GitHub), che costruisce un indice dei contenuti a partire dagli H1-H6 direttamente nella pagina. template: blog_item imposta esplicitamente il template per la pagina figlia del blog, così Grav non lo determina euristicamente a ogni rendering.

Il blocco page-addon è una sezione personalizzata per flag definiti dall'utente. Qui ifarmelazy: true abilita il lazy loading per gli iframe: nel file user/themes/g5_helium/custom/templates/partials/blog_item.html.twig si attiva una condizione che carica lo script di iframe.ly.

1
{% if attribute(page.header, 'page-addon').ifarmelazy %}
2
   <script async charset="utf-8" src="//cdn.iframe.ly/embed.js"></script>
3
{% endif %}
4

Per inserire l'iframe stesso (ad esempio, un video di YouTube), usa questa struttura:

1
<iframe allowfullscreen
2
  data-iframely-url="https://www.youtube.com/embed/54WI1XSilb4"
3
  scrolling="no"
4
  style="border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;">
5
</iframe>

Impostazioni Markdown per gli header dei post

Questa sezione copre i campi specificati nell'header di ogni singolo post.

Titolo e descrizione

1
title: 'Grav + Gantry 5 — an overview of useful extensions and resources'
2
metadata:
3
    description: 'A collection of Grav extensions for Gantry 5 that speed up work with content and templates.'

La descrizione finisce nel <meta name="description"> ed è importante per gli snippet nei risultati di ricerca.

Data di creazione e Auto Date

1
date: '2026-06-14 10:00'

Per fare in modo che la data venga impostata automaticamente alla creazione di una pagina, installa il plugin Auto Date, github.com/getgrav/grav-plugin-auto-date. Inserisce la data e l'ora correnti se il campo date non viene compilato manualmente.

Tassonomie

Per una singola categoria e un singolo tag, sintassi piatta:

1
taxonomy:
2
    category: WEB
3
    tag: Markdown

Per valori multipli, usa il formato lista:

1
taxonomy:
2
    category:
3
    - Grav
4
    tag:
5
    - Grav - Gantry 5
6
    - Grav - Plugins

Page Toc e template

Page Toc genera un sommario a partire dalle intestazioni presenti nel corpo della pagina. Oltre al flag page-toc.active: true nell'intestazione, puoi aggiungere codice Twig direttamente nel template del tema (vedi la sezione Twig più sotto).

template: blog_item va specificato manualmente affinché Grav usi in modo affidabile il template del post figlio del blog, poiché il CMS a volte fallisce con il rilevamento automatico per le nuove pagine.

Preprocessori Markdown e Twig

1
process:
2
    markdown: true
3
    twig: true
4
twig_first: true

twig_first: true indica a Grav di elaborare prima il motore di template Twig e poi Markdown. L'ordine è critico se il corpo della pagina contiene logica Twig che genera markup Markdown.

Evidenziazione della sintassi (Highlight)

Dipende dal plugin Highlight, github.com/getgrav/grav-plugin-highlight.

1
highlight:
2
    enabled: true
3
    lines: true

lines: true aggiunge la numerazione delle righe nei blocchi di codice evidenziati.

Impostazioni Twig per il corpo della pagina

Sommario automatico tramite toc()

Page Toc può funzionare non solo dall'intestazione ma anche tramite inserimento diretto nel template del tema. Nel file user/themes/g5_helium/custom/templates/partials/blog_item.html.twig, aggiungi:

1
{# PAGE TOC START #}
2
{#
3
page-toc:
4
    active: true
5
 #}
6
{% if attribute(page.header, 'page-toc').active %}
7
        {% set table_of_contents = toc(page.content) %}
8
      {% if table_of_contents is not empty %}
9
      Table of contents:
10
      {{ table_of_contents|raw }}
11
      {% endif %}
12
 
13
{% endif %}
14
{# PAGE TOC END #}
15

La funzione Twig toc(page.content) analizza le intestazioni all'interno di page.content e restituisce un albero strutturato. La condizione verifica il flag page-toc.active dall'intestazione, permettendoti di abilitare e disabilitare il sommario per singole pagine senza toccare il template.

Galleria di immagini tramite Unitegallery

Il plugin Unitegallery, github.com/variar/grav-plugin-unitegallery, aggiunge una galleria a Grav basata sulla libreria JS Unitegallery con diversi temi di visualizzazione.

Dopo l'installazione tramite pannello di amministrazione o GPM (Grav Package Manager), si aggiunge una singola riga al corpo della pagina:

1
{{ unite_gallery(page.media.images) | raw }}
2

Rende tutte le immagini caricate nella raccolta media della pagina come una galleria.

Ricerca e sostituzione con Atom per le esportazioni di Writage.md

Quando si esportano post da WordPress a Markdown tramite Writage, i percorsi delle immagini contengono il prefisso media/ e per abilitare il caricamento differito (lazy loading) sono necessarie le classi figure-img e img-fluid. Modificare manualmente ogni URL è inutile; Atom con le espressioni regolari lo fa in un secondo.

Il plugin Lazy Image gestisce il caricamento differito, github.com/unsaturated/grav-plugin-lazy-image.

Trova (espressione regolare):

1
(![.*]()(media/)(.*)())

Sostituisci con variante lightbox (plugin FeatherLight):

1
$1$3)

Sostituisci con solo lazy loading:

1
$1$3?classes=figure-img,img-fluid)

Dopo la sostituzione, l'immagine riceve un parametro di query classes che Lazy Image rileva.

Lavorare con le anteprime

Grav può manipolare dinamicamente le immagini: ridimensionare, ritagliare, mettere in cache. L'anteprima di una pagina si imposta tramite sintassi Markdown con parametri di query:

1
![ALT Image](https://learn.getgrav.org/20/content/media)

Maggiori dettagli sulle funzionalità media nella documentazione ufficiale: learn.getgrav.org/content/media.

Configurazione server Ubuntu 24.04 per Grav

Grav su un VPS richiede PHP, SQLite (per il database interno dei plugin) e preferibilmente Memcached (per la cache delle pagine). Di seguito i comandi aggiornati per Ubuntu 24.04 LTS e PHP 8.3.

Installare PDO SQLite su PHP 8.3

1
sudo apt-get update
2
sudo apt-get install php8.3-sqlite
3
sudo systemctl restart apache2

SQLite è usato da Grav per archiviare log, cache dei plugin e dati di gestione interna. Senza il driver, il pannello di amministrazione andrà in crash con un errore di connessione al database.

Installare Memcached

Istruzioni aggiornate: tecadmin.net/install-memcached-with-php-on-ubuntu/.

1
sudo apt-get update
2
sudo apt-get install memcached
3
 
4
sudo add-apt-repository ppa:ondrej/php
5
sudo apt-get update
6
sudo apt-get install -y php php-dev php-pear libapache2-mod-php
7
 
8
sudo apt-get install -y php-memcached
9
 
10
sudo systemctl restart apache2

File PHP non eseguiti dopo il cambio di versione (Virtualmin/Webmin)

Dopo il passaggio da PHP 7.x a 8.3, Apache potrebbe servire i file .php come testo invece di eseguirli, un comportamento noto quando si cambiano moduli. Il problema sono le direttive SetHandler all'interno della configurazione del modulo PHP.

1
sudo nano /etc/apache2/mods-enabled/php8.3.conf

Commenta queste righe:

1
  # SetHandler application/x-httpd-php
2
  # SetHandler application/x-httpd-php-source

File php8.3.conf finale dopo le modifiche:

1
<filesmatch ".+\.ph(ar|p|tml)$">
2
  # SetHandler application/x-httpd-php
3
</filesmatch>
4
<filesmatch ".+\.phps$">
5
  # SetHandler application/x-httpd-php-source
6
  # Deny access to raw php sources by default
7
  # To re-enable it's recommended to enable access to the files
8
  # only in specific virtual host or directory
9
    Require all denied
10
</filesmatch>
11
 
12
  # Deny access to files without filename (e.g. '.php')
13
&lt;filesmatch &quot;^\.ph(ar|p|ps|tml)$&quot;&gt;
14
    Require all denied
15
</filesmatch>
16
 
17
  # Running PHP scripts in user directories is disabled by default
18
  #
19
  # To re-enable PHP in user directories comment the following lines
20
  # (from <IfModule ...> to </IfModule>.) Do NOT set it to On as it
21
  # prevents .htaccess files from disabling it.
22
<ifmodule mod_userdir.c="">
23
    <directory /home/*/public_html>
24
        php_admin_flag engine Off
25
    </directory>
26
</ifmodule>

Dopo aver modificato, riavvia Apache:

1
sudo systemctl restart apache2

Video: cos'è Grav CMS e da dove iniziare

Una breve introduzione a Grav per chi sente parlare di CMS flat-file per la prima volta: cosa c'è sotto il cofano, come sono strutturati i contenuti e perché funzionare senza database può essere più veloce.

⁉️🤔 Domande frequenti

Grav richiede un database?

No, Grav è un CMS flat-file. Tutti i contenuti, le impostazioni, le tassonomie e i metadati sono archiviati in file di testo (Markdown e YAML). SQLite è usato in modo opzionale per esigenze interne: cache dei plugin, log, code. PostgreSQL e MySQL non sono ufficialmente richiesti. In pratica questo significa che fare il backup di un sito equivale a copiare la cartella /user.

Il plugin Page Toc è obbligatorio per l'indice dei contenuti?

Può essere sostituito con codice Twig diretto usando toc(page.content) nel template del tema. Ma il plugin è più comodo per attivarlo e disattivarlo rapidamente tramite un flag nel frontmatter YAML di una pagina specifica. Se il tuo sito ha più di 50 pagine, gestirlo tramite l'intestazione è più pratico che inserire condizioni nel template.

In cosa si differenzia Highlight da Prism.js o Highlight.js?

Highlight è il plugin ufficiale di Grav che integra highlight.js direttamente nella pipeline di rendering. Interpreta i flag enabled e lines dall'intestazione YAML e non richiede l'inclusione manuale di JS/CSS; GPM gestisce tutto. Prism.js andrebbe incluso manualmente nel tema.

Grav è ancora rilevante nel 2026 rispetto a WordPress?

Per certi scenari, sì. Grav è vincente per siti vetrina statici, portfolio, documentazione e landing page dove non servono logiche utente complesse ed e-commerce. L'architettura flat-file garantisce una risposta immediata senza database e il versionamento dei contenuti funziona tramite Git. Ma per un blog con migliaia di articoli, una libreria media e archivi dinamici, WordPress è più pratico per via del suo ecosistema di plugin.

Cosa fare se il pannello di amministrazione di Grav smette di funzionare dopo un aggiornamento di PHP?

Tre cause tipiche: (1) php8.x-sqlite non è installato e Grav va in crash silenziosamente senza il driver del database; (2) SetHandler non è commentato in php8.x.conf quando si usa Virtualmin e Apache serve .php come testo; (3) i permessi sulle cartelle cache/, logs/ e backup/ dentro /user sono stati resettati, quindi esegui chown -R www-data:www-data user/.

Cheat sheet pronto all'uso: cosa copiare nel tuo progetto

Sei file e plugin che avviano un tipico progetto Grav su VPS: intestazione con tassonomie e page-toc, indice dei contenuti Twig nel template, preprocessore Markdown, Highlight, Unitegallery e regex Atom per l'esportazione in post-produzione. Aggiungi la configurazione del server dalla sezione Ubuntu 24.04 e avrai un ambiente completamente pronto in mezz'ora. Tieni questa pagina nei preferiti; aggiorniamo gli snippet per le versioni correnti di Grav e PHP.