Grav

Siehe auch

Verwandte Artikel
Offizielle Dokumentation
Linuxfabrik

Grav ist ein flat-file CMS von Trilby Media: Inhalte liegen als Markdown-Dateien im Dateisystem, gerendert wird über Twig-Templates, eine Datenbank gibt es nicht. Plugins, Themes und Grav selbst verwaltet der Grav Package Manager (GPM) über bin/gpm.

Zum Download gibt es zwei Varianten. Das Paket grav enthält nur den Kern, das Paket grav-admin zusätzlich das Admin-Plugin mit einer Web-Oberfläche zum Bearbeiten von Seiten. Wer Inhalte als Markdown-Dateien pflegt und per Git deployt, kommt ohne Admin-Plugin aus.

Das Standard-Theme ist Quark. Es bringt das CSS-Framework Spectre.css mit. Eigene Themes leiten üblicherweise per Twig-Namespace @quark von Quark ab und überschreiben nur einzelne Templates.

Installation zur lokalen Entwicklung

Für die lokale Entwicklung genügen PHP, das Grav-ZIP und der eingebaute PHP-Webserver. Das ist nicht für den produktiven Betrieb gedacht (siehe unten).

Grav verlangt PHP 7.3.6 oder neuer (RHEL 10 liefert PHP 8.3) und die Extensions curl, dom, gd, json, libxml, openssl und zip. curl, json und openssl stecken auf RHEL bereits in php-common, die übrigen kommen aus den folgenden Paketen:

sudo dnf -y install php-cli php-gd php-mbstring php-xml php-zip

Grav herunterladen und mit dem eingebauten Webserver starten:

# Grav core (use ".../core/grav-admin/latest" to include the Admin plugin)
wget --output-document=grav.zip https://getgrav.org/download/core/grav/latest
unzip grav.zip

cd grav
php -S localhost:8080 system/router.php

Die Seite ist danach unter http://localhost:8080 erreichbar.

Plugins

Plugins installiert GPM aus dem offiziellen Repository:

bin/gpm install <plugin>

Die Standard-Konfiguration eines Plugins liegt in dessen Verzeichnis. Zum Anpassen wird sie nach user/config/plugins/ kopiert und dort editiert, damit ein Update sie nicht überschreibt. Beispiel Language Switcher:

bin/gpm install langswitcher
cp user/plugins/langswitcher/langswitcher.yaml user/config/plugins/langswitcher.yaml

Den Umschalter bindet das Theme im passenden Template ein:

user/themes/mytheme/templates/partials/base.html.twig
{% if config.plugins.langswitcher.enabled %}
    <span>{% include 'partials/langswitcher.html.twig' %}</span>
{% endif %}

Praktische Plugins, die auch die Linuxfabrik-Website einsetzt:

  • archives: Blog-Archiv nach Monat und Jahr

  • breadcrumbs: Brotkrumen-Navigation

  • devtools: Gerüste für eigene Plugins und Themes, Voraussetzung für Theme-Inheritance

  • error: eigene Fehlerseiten

  • external_links: markiert externe Links und öffnet sie in einem neuen Tab

  • feed: Atom- und RSS-Feed

  • form: Formulare

  • langswitcher: Sprachumschalter

  • markdown-notices: Hinweisboxen (!!! note, !!! tip)

  • pagination: Blättern in Listen

  • sitemap: XML-Sitemap

  • taxonomylist: Tag- und Kategorie-Listen

Themes

Theme installieren:

bin/gpm install <theme>

Ein bestehendes Theme per Inheritance erweitern, statt es zu kopieren. Dazu das devtools-Plugin nutzen:

bin/gpm install devtools
bin/plugin devtools new-theme

Please choose an option:
[pure-blank  ] Basic Theme using Pure.css
[tailwind    ] Basic Theme using tailwind.css and including Alpine.js
[tailwind-mix] Same as `tailwind` but more opinionated with Laravel Mix compiler
[inheritance ] Inherit from another theme
[copy        ] Copy another theme
> inheritance

Please choose a theme to extend:
[0] quark
> 0

Ein so erzeugtes Theme erbt alle Templates und Assets des Eltern-Themes und überschreibt nur, was abweicht. Aus Quark abgeleitete Templates erreichen das Original über den Namespace @quark.

Neues Projekt aus einem Skeleton

Ein Skeleton ist eine fertige Webseite aus Theme, Plugins und Beispielinhalten als Startpunkt. Ein bekanntes Beispiel ist das One-Page-Skeleton.

Ein neues Projekt inklusive aller Abhängigkeiten anlegen:

bin/grav new-project

Ein leeres Grundgerüst zum Ausprobieren im aktuellen Webroot erzeugt bin/grav sandbox.

Updates und Cache

Grav-Kern aktualisieren:

bin/gpm selfupgrade --force --all-yes

Plugins und Themes aktualisieren:

bin/gpm update --all-yes

Diese Befehle als der User ausführen, dem die Installation gehört (im produktiven Betrieb der Webserver-User). Nach Änderungen an Templates, Twig oder Plugins den Cache leeren:

bin/grav clearcache

Produktiver Betrieb

Im produktiven Betrieb läuft Grav hinter einem echten Webserver, etwa Apache mit php-fpm oder nginx mit php-fpm. Das Document Root zeigt auf das Grav-Verzeichnis. Beispiel-Konfigurationen liefert das Grav-Paket im Verzeichnis webserver-configs/ mit (htaccess.txt für Apache, nginx.conf, lighttpd.conf, Caddyfile und web.config für IIS).

Der Webserver-User (auf RHEL apache) braucht Schreibrechte auf die von Grav beschriebenen Verzeichnisse (cache, logs, images, backup, tmp und user). Die Details und die SELinux-tauglichen Kontexte stehen in der offiziellen Doku unter Permissions.

Steht Grav hinter einem TLS-terminierenden Reverse Proxy, der das Klartext-HTTP an das Backend weiterreicht, gehören in die user/config/system.yaml die Einträge reverse_proxy_setup: true und http_x_forwarded.protocol: true. Sonst erzeugt Grav Links mit http statt https.