Lorsque vous travaillez avec Grav CMS depuis plusieurs années, vous accumulez un ensemble d’extraits qui voyagent de projet en projet. Frontmatter YAML, templates Twig, configurations de coloration syntaxique, motifs regex pour Atom: fouiller dans la documentation ou dans un ancien dépôt à chaque fois fait perdre du temps. Surtout quand Grav tourne sur un VPS et que vous devez vous rappeler comment installer correctement le pilote SQLite pour PHP 8.3 ou commenter SetHandler après une mise à jour d’Apache.

Cette antisèche est une distillation issue de la pratique réelle: en-tête par défaut, paramètres Markdown pour les pages, extraits Twig dans le corps des articles, regex Atom pour le post-traitement des exports.md, et commandes serveur Ubuntu. Le tout au même endroit, avec des explications sur le quoi et le pourquoi.

💡 Aperçu rapide:

• Configurer le frontmatter YAML Grav avec tous les champs: taxonomie, page-toc, highlight, process, page-addon personnalisé
• Mettre en place la logique Markdown dans les en-têtes de page: titre, description, date, taxonomies, template
• Ajouter du code Twig dans le corps: table des matières automatique via toc(), galerie Unitegallery
• Traiter les exports Writage.md dans Atom: remplacement de media/ dans les chemins, ajout de classes pour le lazy load
• Configurer l’environnement serveur: SQLite, Memcached, PHP 8.3 sur Ubuntu 24.04, édition de php*.conf pour Virtualmin

En-tête Grav par défaut pour toutes les pages du site

Le frontmatter YAML de base d’une page Grav inclut les champs que le CMS lit lors du rendu. Voici un modèle fonctionnel couvrant la plupart des tâches courantes: des taxonomies aux drapeaux personnalisés de 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 active le plugin Page Toc (GitHub), qui construit une table des matières à partir des H1-H6 directement sur la page. template: blog_item définit explicitement le template de page enfant du blog afin que Grav ne le détermine pas de manière heuristique à chaque rendu.

Le bloc page-addon est une section personnalisée pour des drapeaux définis par l’utilisateur. Ici, ifarmelazy: true active le lazy loading pour les iframes: dans le fichier user/themes/g5_helium/custom/templates/partials/blog_item.html.twig, une condition se déclenche, chargeant le script 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

Pour insérer l’iframe elle-même (par exemple, une vidéo YouTube), utilisez cette structure:

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>

Paramètres Markdown pour les en-têtes de page d’article

Cette section couvre les champs spécifiés dans l’en-tête de chaque article individuel.

Titre et description

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 description est placée dans <meta name="description"> et est importante pour les extraits dans les résultats de recherche.

Date de création et Auto Date

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

Pour que la date soit automatiquement définie lors de la création d’une page, installez le plugin Auto Date, github.com/getgrav/grav-plugin-auto-date. Il insère la date et l’heure actuelles si le champ date n’est pas rempli manuellement.

Taxonomies

Pour une seule catégorie et un seul tag, syntaxe plate:

1
taxonomy:
2
    category: WEB
3
    tag: Markdown

Pour plusieurs valeurs, utilisez le format de liste:

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

Table des matières et template de page

La fonction Page Toc génère une table des matières à partir des titres présents dans le corps de la page. En plus du flag page-toc.active: true dans l'en-tête, vous pouvez ajouter du code Twig directement dans le template du thème (voir la section Twig ci-dessous).

template: blog_item est spécifié manuellement pour que Grav utilise de manière fiable le template des articles de blog, car le CMS échoue parfois dans l'auto-détection pour les nouvelles pages.

Préprocesseurs Markdown et Twig

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

twig_first: true signifie que Grav va d'abord traiter le moteur de template Twig, puis le Markdown. L'ordre est critique si le corps de la page contient de la logique Twig qui génère du balisage Markdown.

Coloration syntaxique (Highlight)

Dépend du plugin Highlight, github.com/getgrav/grav-plugin-highlight.

1
highlight:
2
    enabled: true
3
    lines: true

lines: true ajoute la numérotation des lignes dans les blocs de code colorisés.

Paramètres Twig pour le corps de page

Table des matières automatique via toc()

Page Toc peut fonctionner non seulement depuis l'en-tête mais aussi par insertion directe dans le template du thème. Dans le fichier user/themes/g5_helium/custom/templates/partials/blog_item.html.twig, ajoutez:

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 fonction Twig toc(page.content) analyse les titres dans page.content et retourne une arborescence structurée. La condition vérifie le flag page-toc.active de l'en-tête, ce qui vous permet d'activer et de désactiver la table des matières pour des pages individuelles sans toucher au template.

Galerie d'images via Unitegallery

Le plugin Unitegallery, github.com/variar/grav-plugin-unitegallery, ajoute une galerie à Grav basée sur la bibliothèque JS Unitegallery avec plusieurs thèmes d'affichage.

Après installation via le panneau d'administration ou GPM (Grav Package Manager), une seule ligne est ajoutée au corps de la page:

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

Elle restitue toutes les images téléchargées dans la collection média de la page sous forme de galerie.

Recherche et remplacement Atom pour les exports Writage.md

Lors de l'export de posts WordPress vers Markdown via Writage, les chemins d'images contiennent le préfixe media/, et l'activation du lazy loading nécessite les classes figure-img et img-fluid. Modifier manuellement chaque URL n'a pas de sens; Atom avec des expressions régulières le fait en une seconde.

Le plugin Lazy Image gère le lazy loading, github.com/unsaturated/grav-plugin-lazy-image.

Rechercher (expression régulière):

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

Remplacer par la variante lightbox (plugin FeatherLight):

1
$1$3)

Remplacer par le lazy loading seul:

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

Après remplacement, l'image reçoit un paramètre de requête classes que Lazy Image détecte.

Travailler avec les vignettes

Grav peut manipuler les images dynamiquement: redimensionner, recadrer, mettre en cache. Une vignette de page se définit via la syntaxe Markdown avec des paramètres de requête:

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

Plus d'informations sur les capacités média dans la documentation officielle: learn.getgrav.org/content/media.

Configuration d'un serveur Ubuntu 24.04 pour Grav

Grav sur un VPS nécessite PHP, SQLite (pour la base de données interne des plugins) et, de préférence, Memcached (pour la mise en cache des pages). Voici les commandes actuelles pour Ubuntu 24.04 LTS et PHP 8.3.

Installer PDO SQLite sur PHP 8.3

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

SQLite est utilisé par Grav pour stocker les journaux, le cache des plugins et la comptabilité interne. Sans ce pilote, le panneau d'administration plantera avec une erreur de connexion à la base de données.

Installer Memcached

Instructions actuelles: 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

Les fichiers PHP ne s'exécutent pas après un changement de version (Virtualmin/Webmin)

Après le passage de PHP 7.x à 8.3, Apache peut afficher les fichiers .php comme du texte au lieu de les exécuter, un comportement connu lors du changement de modules. Le problème vient des directives SetHandler dans la configuration du module PHP.

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

Commentez ces lignes:

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

Fichier php8.3.conf final après modification:

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>

Après modification, redémarrez Apache:

1
sudo systemctl restart apache2

Vidéo: qu'est-ce que Grav CMS et par où commencer

Une courte introduction à Grav pour ceux qui découvrent le CMS flat-file: ce qu'il y a sous le capot, comment le contenu est structuré et pourquoi fonctionner sans base de données peut être plus rapide.

⁉️🤔 Foire aux questions

Grav nécessite-t-il une base de données?

Non, Grav est un CMS à fichiers plats. Tout le contenu, les paramètres, les taxonomies et les métadonnées sont stockés dans des fichiers texte (Markdown et YAML). SQLite est utilisé de manière optionnelle pour des besoins internes: cache des plugins, journaux, files d’attente. PostgreSQL et MySQL ne sont pas officiellement requis. En pratique, cela signifie que sauvegarder un site revient simplement à copier le dossier /user.

Le plugin Page Toc est-il obligatoire pour la table des matières?

Il peut être remplacé par du code Twig direct utilisant toc(page.content) dans le template du thème. Mais le plugin est plus pratique pour une activation/désactivation rapide via un indicateur dans l’en-tête YAML d’une page spécifique. Si votre site compte plus de 50 pages, la gestion par l’en-tête est plus pratique que des branchements conditionnels dans le template.

En quoi Highlight diffère-t-il de Prism.js ou Highlight.js?

Highlight est le plugin Grav officiel qui intègre highlight.js directement dans le pipeline de rendu. Il comprend les indicateurs enabled et lines de l’en-tête YAML et ne nécessite pas d’inclusion manuelle de JS/CSS; GPM gère tout. Prism.js devrait être inclus manuellement dans le thème.

Grav est-il toujours pertinent en 2026 par rapport à WordPress?

Pour certains scénarios, oui. Grav est imbattable pour les sites vitrine statiques, les portfolios, la documentation et les pages d’atterrissage où une logique utilisateur complexe et le e-commerce ne sont pas nécessaires. L’architecture à fichiers plats offre une réponse instantanée sans base de données, et le versionnement du contenu fonctionne via Git. Mais pour un blog avec des milliers d’articles, une médiathèque et des archives dynamiques, WordPress est plus pratique en raison de son écosystème de plugins.

Que faire si le panneau d’administration Grav cesse de fonctionner après une mise à jour PHP?

Trois causes typiques: (1) php8.x-sqlite n’est pas installé, et Grav plante silencieusement sans le pilote de base de données; (2) SetHandler n’est pas commenté dans php8.x.conf lors de l’utilisation de Virtualmin, et Apache sert les .php comme du texte; (3) les permissions des dossiers cache/, logs/ et backup/ à l’intérieur de /user ont été réinitialisées, il faut donc exécuter chown -R www-data:www-data user/.

Aide-mémoire prêt à l’emploi: ce qu’il faut copier dans votre projet

Six fichiers et plugins qui lancent un projet Grav typique sur un VPS: en-tête avec taxonomies et page-toc, table des matières Twig dans le template, préprocesseur Markdown, Highlight, Unitegallery et expression régulière Atom pour le post-traitement des exports. Ajoutez la configuration serveur de la section Ubuntu 24.04, et vous disposez d’un environnement entièrement prêt en une demi-heure. Gardez cette page dans vos favoris; nous mettons à jour les extraits pour les versions actuelles de Grav et PHP.