Wenn Sie mehrere Jahre mit Grav CMS gearbeitet haben, sammelt sich ein Satz an Snippets an, die von Projekt zu Projekt mitwandern. YAML-Frontmatter, Twig-Templates, Syntax-Highlighting-Konfigurationen, Atom-Regex-Muster: Jedes Mal in der Dokumentation oder einem alten Repository zu graben, kostet Zeit. Besonders dann, wenn Grav auf einem VPS läuft und Sie sich merken müssen, wie man den SQLite-Treiber für PHP 8.3 korrekt installiert oder nach einem Apache-Update SetHandler auskommentiert.

Dieser Spickzettel ist eine Destillation aus der Praxis: Standard-Header, Markdown-Einstellungen für Seiten, Twig-Snippets im Beitragstext, Atom-Regex für den Export von post-processing.md und Ubuntu-Server-Befehle. Alles an einem Ort, mit Erläuterungen zum Was und Warum.

💡 Kurzüberblick:

• Grav YAML-Frontmatter mit allen Feldern konfigurieren: Taxonomy, page-toc, highlight, process, benutzerdefiniertes page-addon
• Markdown-Logik in Seiten-Headern einrichten: title, description, date, taxonomies, template
• Twig-Code in den Body einfügen: automatisches Inhaltsverzeichnis via toc(), Unitegallery-Galerie
• Writage.md-Exporte in Atom verarbeiten: media/ in Pfaden ersetzen, Klassen für Lazy Load übergeben
• Server-Umgebung einrichten: SQLite, Memcached, PHP 8.3 auf Ubuntu 24.04, php*.conf für Virtualmin bearbeiten

Grav-Standard-Header für alle Seiten der Website

Das grundlegende YAML-Frontmatter einer Grav-Seite enthält Felder, die das CMS während des Renderns ausliest. Unten sehen Sie eine funktionierende Vorlage, die die meisten typischen Aufgaben abdeckt: von Taxonomien bis zu benutzerdefinierten page-addon-Flags.

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 aktiviert das Page Toc-Plugin (GitHub), das direkt auf der Seite ein Inhaltsverzeichnis aus H1-H6 erstellt. template: blog_item setzt explizit das Template für Blog-Unterseiten, damit Grav es nicht bei jedem Rendern heuristisch ermitteln muss.

Der page-addon-Block ist ein benutzerdefinierter Abschnitt für selbstdefinierte Flags. Hier aktiviert ifarmelazy: true das Lazy Loading für Iframes: In der Datei user/themes/g5_helium/custom/templates/partials/blog_item.html.twig greift eine Bedingung, die das iframe.ly-Skript lädt.

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

Um das Iframe selbst einzufügen (zum Beispiel ein YouTube-Video), verwenden Sie diese Struktur:

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>

Markdown-Einstellungen für Beitrags-Seiten-Header

Dieser Abschnitt behandelt Felder, die im Header jedes einzelnen Beitrags angegeben werden.

Titel und Beschreibung

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.'

Die Beschreibung fließt in <meta name="description"> ein und ist wichtig für Suchergebnis-Snippets.

Erstellungsdatum und Auto Date

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

Damit das Datum beim Anlegen einer Seite automatisch gesetzt wird, installieren Sie das Auto Date-Plugin, github.com/getgrav/grav-plugin-auto-date. Es fügt das aktuelle Datum und die Uhrzeit ein, falls das Feld date nicht manuell befüllt wird.

Taxonomien

Für eine einzelne Kategorie und einen einzelnen Tag, flache Syntax:

1
taxonomy:
2
    category: WEB
3
    tag: Markdown

Für mehrere Werte verwenden Sie das Listenformat:

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

Seiten-Inhaltsverzeichnis und Template

Das Seiten-Inhaltsverzeichnis (Page Toc) generiert ein Inhaltsverzeichnis aus den Überschriften im Seitenkörper. Neben dem Flag page-toc.active: true im Header können Sie Twig-Code direkt in das Theme-Template einfügen (siehe den Twig-Abschnitt unten).

template: blog_item wird manuell angegeben, damit Grav zuverlässig das Template für Blog-Beitragsseiten verwendet, da das CMS bei der automatischen Erkennung neuer Seiten gelegentlich versagt.

Markdown- und Twig-Präprozessoren

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

twig_first: true bedeutet, dass Grav zuerst die Twig-Template-Engine verarbeitet und danach Markdown. Die Reihenfolge ist entscheidend, wenn der Seitenkörper Twig-Logik enthält, die Markdown-Markup generiert.

Syntaxhervorhebung (Highlight)

Hängt vom Highlight-Plugin ab, github.com/getgrav/grav-plugin-highlight.

1
highlight:
2
    enabled: true
3
    lines: true

lines: true fügt in hervorgehobenen Codeblöcken Zeilennummern hinzu.

Twig-Einstellungen für den Seitenkörper

Automatisches Inhaltsverzeichnis via toc()

Das Seiten-Inhaltsverzeichnis kann nicht nur über den Header, sondern auch durch direkte Einbindung im Theme-Template funktionieren. Fügen Sie in der Datei user/themes/g5_helium/custom/templates/partials/blog_item.html.twig Folgendes hinzu:

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

Die Twig-Funktion toc(page.content) analysiert die Überschriften innerhalb von page.content und gibt eine strukturierte Baumansicht zurück. Die Bedingung prüft das Flag page-toc.active aus dem Header, sodass Sie das Inhaltsverzeichnis für einzelne Seiten ein- und ausschalten können, ohne das Template anfassen zu müssen.

Bildergalerie via Unitegallery

Das Unitegallery-Plugin, github.com/variar/grav-plugin-unitegallery, fügt Grav eine Galerie hinzu, die auf der Unitegallery-JS-Bibliothek mit mehreren Anzeigethemen basiert.

Nach der Installation über das Admin-Panel oder GPM (Grav Package Manager) wird eine einzelne Zeile in den Seitenkörper eingefügt:

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

Sie rendert alle Bilder, die in die Medienkollektion der Seite hochgeladen wurden, als Galerie.

Atom-Suchen-und-Ersetzen für Writage.md-Exporte

Wenn Sie WordPress-Beiträge mit Writage nach Markdown exportieren, enthalten die Bildpfade das Präfix media/, und für die Aktivierung von Lazy Loading sind die Klassen figure-img und img-fluid erforderlich. Jede URL manuell zu bearbeiten, ist nicht sinnvoll; Atom erledigt das mit regulären Ausdrücken in einer Sekunde.

Das Lazy Image-Plugin übernimmt das Lazy Loading, github.com/unsaturated/grav-plugin-lazy-image.

Suchen (regulärer Ausdruck):

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

Ersetzen mit Lightbox-Variante (FeatherLight-Plugin):

1
$1$3)

Ersetzen mit reinem Lazy Loading:

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

Nach der Ersetzung erhält das Bild einen classes-Query-Parameter, den Lazy Image auswertet.

Arbeiten mit Vorschaubildern

Grav kann Bilder dynamisch bearbeiten: skalieren, zuschneiden, cachen. Ein Seiten-Thumbnail wird über die Markdown-Syntax mit Query-Parametern gesetzt:

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

Mehr zu den Medienfunktionen in der offiziellen Dokumentation: learn.getgrav.org/content/media.

Ubuntu-24.04-Server-Setup für Grav

Grav auf einem VPS benötigt PHP, SQLite (für die interne Plugin-Datenbank) und vorzugsweise Memcached (Seiten-Caching). Nachfolgend die aktuellen Befehle für Ubuntu 24.04 LTS und PHP 8.3.

PDO SQLite unter PHP 8.3 installieren

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

SQLite wird von Grav zum Speichern von Logs, Plugin-Cache und für die interne Buchhaltung verwendet. Ohne den Treiber stürzt das Admin-Panel mit einem Datenbankverbindungsfehler ab.

Memcached installieren

Aktuelle Anleitung: 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

PHP-Dateien werden nach Versionswechsel nicht ausgeführt (Virtualmin/Webmin)

Nach dem Wechsel von PHP 7.x auf 8.3 kann es vorkommen, dass Apache .php-Dateien als Text ausliefert, anstatt sie auszuführen, ein bekanntes Verhalten beim Wechsel von Modulen. Das Problem liegt in den SetHandler-Direktiven innerhalb der PHP-Modulkonfiguration.

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

Kommentieren Sie diese Zeilen aus:

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

Die endgültige php8.3.conf nach der Bearbeitung:

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>

Starten Sie Apache nach der Bearbeitung neu:

1
sudo systemctl restart apache2

Video: Was Grav CMS ist und wo Sie anfangen

Eine kurze Einführung in Grav für alle, die zum ersten Mal von einem Flat-File-CMS hören: was unter der Haube steckt, wie Inhalte strukturiert sind und warum der Betrieb ohne Datenbank schneller sein kann.

⁉️🤔 Häufig gestellte Fragen

Benötigt Grav eine Datenbank?

Nein, Grav ist ein Flat-File-CMS. Alle Inhalte, Einstellungen, Taxonomien und Metadaten werden in Textdateien gespeichert (Markdown und YAML). SQLite wird optional für interne Zwecke genutzt: Plugin-Cache, Logs, Queues. PostgreSQL und MySQL sind offiziell nicht erforderlich. In der Praxis bedeutet das, dass ein Backup der Site schlicht das Kopieren des /user-Ordners ist.

Ist das Page-Toc-Plugin für ein Inhaltsverzeichnis zwingend erforderlich?

Es lässt sich durch direkten Twig-Code mit toc(page.content) im Theme-Template ersetzen. Das Plugin ist jedoch bequemer, um es schnell über ein Flag im YAML-Frontmatter einer bestimmten Seite ein- oder auszuschalten. Bei 50+ Seiten ist die Steuerung über den Header praktikabler als eine Verzweigung im Template.

Wie unterscheidet sich Highlight von Prism.js oder Highlight.js?

Highlight ist das offizielle Grav-Plugin, das highlight.js direkt in die Rendering-Pipeline einbindet. Es versteht die Flags enabled und lines aus dem YAML-Header und erfordert keine manuelle Einbindung von JS/CSS; GPM übernimmt alles. Prism.js müsste manuell im Theme eingebunden werden.

Ist Grav 2026 im Vergleich zu WordPress noch relevant?

Für bestimmte Szenarien ja. Grav punktet bei statischen Visitenkarten-Sites, Portfolios, Dokumentationen und Landingpages, wo keine komplexe Benutzerlogik und kein E-Commerce benötigt werden. Die Flat-File-Architektur liefert sofortige Antwortzeiten ohne Datenbank, und die Versionierung von Inhalten funktioniert über Git. Für ein Blog mit tausenden Beiträgen, einer Mediathek und dynamischen Archiven ist WordPress aufgrund seines Plugin-Ökosystems jedoch praktikabler.

Was tun, wenn das Grav-Admin-Panel nach einem PHP-Update nicht mehr funktioniert?

Drei typische Ursachen: (1) php8.x-sqlite ist nicht installiert, und Grav stürzt ohne den Datenbanktreiber stillschweigend ab; (2) SetHandler ist in der php8.x.conf bei Verwendung von Virtualmin nicht auskommentiert, und Apache liefert .php als Text aus; (3) Die Berechtigungen der Ordner cache/, logs/ und backup/ innerhalb von /user wurden zurückgesetzt, führen Sie daher chown -R www-data:www-data user/ aus.

Fertiger Spickzettel: Was Sie in Ihr Projekt übernehmen können

Sechs Dateien und Plugins, die ein typisches Grav-Projekt auf einem VPS starten: Header mit Taxonomien und Page-Toc, Twig-Inhaltsverzeichnis im Template, Markdown-Preprocessor, Highlight, Unitegallery und Atom-Regex für den Post-Processing-Export. Ergänzen Sie das Server-Setup aus dem Abschnitt Ubuntu 24.04, und Sie haben in einer halben Stunde eine vollständig einsatzbereite Umgebung. Setzen Sie ein Lesezeichen auf diese Seite; wir aktualisieren die Snippets für aktuelle Grav- und PHP-Versionen.