Kiedy pracuje się z Grav CMS nie pierwszy rok, gromadzi się zestaw snippetów, które wędrują z projektu do projektu. YAML-frontmatter, szablony Twig, konfiguracje podświetlania składni, wyrażenia regularne dla Atom, za każdym razem zaglądanie do dokumentacji lub starego repozytorium to marnowanie czasu. Szczególnie gdy Grav stoi na VPS i trzeba sobie przypomnieć, jak poprawnie zainstalować sterownik sqlite pod PHP 8.3 albo zakomentować SetHandler po aktualizacji Apache.

Ta ściąga to wyciąg z realnej praktyki: domyślny header, ustawienia Markdown dla stron, snippety Twig w treści wpisu, wyrażenia regularne Atom do postprocessingu eksportów.md i polecenia serwerowe Ubuntu. Wszystko w jednym miejscu, z wyjaśnieniami co i dlaczego.

💡 Szybki przegląd:

• Skonfigurować YAML-frontmatter Grav ze wszystkimi polami: taxonomy, page-toc, highlight, process, niestandardowe page-addon
• Zapisać logikę Markdown w headerze stron: title, description, data, taksonomie, szablon
• Dodać kod Twig w treści: auto-spis treści przez toc(), galeria Unitegallery
• Przetworzyć eksporty.md z Writage w Atom: zamiana media/ w ścieżkach, przekazywanie klas dla lazy load
• Postawić środowisko serwerowe: SQLite, Memcached, PHP 8.3 na Ubuntu 24.04, poprawka php*.conf pod Virtualmin

Grav, domyślny header dla wszystkich stron witryny

Podstawowy YAML-frontmatter strony Grav zawiera pola, które CMS odczytuje podczas renderowania. Poniżej działający szablon, który pokrywa większość typowych zadań: od taksonomii po niestandardowe flagi 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 - Плагины
12
    - WordPress - Админка
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 aktywuje wtyczkę Page Toc (GitHub), która buduje spis treści na podstawie H1-H6 bezpośrednio na stronie. template: blog_item sztywno ustawia szablon strony podrzędnej bloga, aby Grav nie określał go heurystycznie przy każdym renderowaniu.

Blok page-addon to niestandardowa sekcja na flagi użytkownika. Tutaj ifarmelazy: true włącza leniwe ładowanie iframe: w pliku user/themes/g5_helium/custom/templates/partials/blog_item.html.twig uruchamia się warunek, który dołącza skrypt 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

Do wstawienia samego iframe (na przykład wideo z YouTube) używa się konstrukcji:

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>

Ustawienia Markdown, nagłówki stron wpisów

Sekcja odpowiada za pola, które zapisuje się w headerze każdego konkretnego wpisu.

Title i Description

1
title: 'Grav + Gantry 5 — обзор полезных расширений и ресурсов'
2
metadata:
3
    description: 'Подборка расширений Grav с Gantry 5, которые ускоряют работу с контентом и шаблонами.'

Description trafia do <meta name="description"> i jest ważny dla snippetu w wynikach wyszukiwania.

Data utworzenia oraz Auto Date

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

Aby data była wstawiana automatycznie podczas tworzenia strony, należy zainstalować wtyczkę Auto Date, github.com/getgrav/grav-plugin-auto-date. Podstawia ona bieżącą datę i czas, jeśli pole date nie jest wypełnione ręcznie.

Taksonomie

Dla jednej kategorii i jednego tagu, składnia płaska:

1
taxonomy:
2
    category: WEB
3
    tag: Markdown

Dla wielu wartości, lista:

1
taxonomy:
2
    category:
3
    - Grav
4
    tag:
5
    - Grav - Gantry 5
6
    - Grav - Плагины

Page Toc i szablon

Page Toc generuje spis treści na podstawie nagłówków wewnątrz treści strony. Oprócz flagi page-toc.active: true w nagłówku, można dodać kod Twig bezpośrednio w szablonie motywu (patrz sekcja Twig poniżej).

template: blog_item wpisuje się ręcznie, aby Grav na pewno użył szablonu podrzędnego wpisu bloga, CMS czasem myli się przy automatycznym wykrywaniu dla nowych stron.

Preprocesory Markdown i Twig

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

twig_first: true oznacza, że Grav najpierw przetworzy silnik szablonów Twig, a następnie Markdown. Kolejność jest krytyczna, jeśli w treści strony znajduje się logika Twig, która generuje znaczniki Markdown.

Podświetlanie składni (Highlight)

Zależy od wtyczki Highlight, github.com/getgrav/grav-plugin-highlight.

1
highlight:
2
    enabled: true
3
    lines: true

lines: true dodaje numerację wierszy w blokach kodu z podświetlaniem.

Ustawienia Twig dla treści stron

Automatyczny spis treści przez toc()

Page Toc może działać nie tylko z nagłówka, ale także przez bezpośrednie wstawienie w szablonie motywu. W pliku user/themes/g5_helium/custom/templates/partials/blog_item.html.twig należy wpisać:

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
      Содержание:
10
      {{ table_of_contents|raw }}
11
      {% endif %}
12
 
13
{% endif %}
14
{# PAGE TOC END #}
15

Funkcja Twig toc(page.content) parsuje nagłówki wewnątrz page.content i zwraca ustrukturyzowane drzewo. Warunek sprawdza flagę page-toc.active z nagłówka, dzięki czemu spis treści można włączać i wyłączać dla poszczególnych stron, nie ruszając szablonu.

Galeria obrazów przez Unitegallery

Wtyczka Unitegallery, github.com/variar/grav-plugin-unitegallery dodaje do Grav galerię opartą na bibliotece JS Unitegallery z kilkoma motywami wyświetlania.

Po instalacji przez panel administracyjny lub GPM (Grav Package Manager) w treści strony dodaje się jeden wiersz:

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

Renderuje on wszystkie obrazy, załadowane do kolekcji mediów strony, w postaci galerii.

Atom, wyszukiwanie i zamiana dla eksportów.md z Writage

Podczas eksportu postów WordPress do Markdown przez Writage ścieżki do obrazów zawierają prefiks media/, a do włączenia leniwego ładowania potrzebne są klasy figure-img i img-fluid. Ręczne poprawianie każdego URL nie ma sensu, Atom z wyrażeniami regularnymi robi to w sekundę.

Za leniwe ładowanie odpowiada wtyczka Lazy Image, github.com/unsaturated/grav-plugin-lazy-image.

Znajdź (wyrażenie regularne):

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

Zamień, wariant z lightboksem (wtyczka FeatherLight):

1
$1$3)

Zamień, wariant tylko z leniwym ładowaniem:

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

Po zamianie obraz otrzymuje parametr zapytania classes, który jest przechwytywany przez Lazy Image.

Praca z miniaturami

Grav potrafi dynamicznie manipulować obrazami: zmieniać rozmiar, przycinać, buforować. Miniaturę strony definiuje się za pomocą składni Markdown z parametrami zapytania:

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

Więcej o możliwościach medialnych w oficjalnej dokumentacji: learn.getgrav.org/content/media.

Ubuntu 24.04, konfiguracja serwerowa dla Grav

Grav na VPS wymaga PHP, SQLite (dla wewnętrznej bazy danych wtyczek) i zalecany jest Memcached (buforowanie stron). Poniżej aktualne polecenia dla Ubuntu 24.04 LTS i PHP 8.3.

Instalacja PDO SQLite na PHP 8.3

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

SQLite jest używany przez Grav do przechowywania logów, bufora wtyczek i wewnętrznej księgowości. Bez sterownika panel administracyjny ulegnie awarii z błędem połączenia z bazą danych.

Instalacja Memcached

Aktualna instrukcja: 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

Pliki PHP nie są wykonywane po zmianie wersji (Virtualmin/Webmin)

Po przejściu z PHP 7.x na 8.3 Apache może serwować pliki .php jako tekst zamiast je wykonywać, znane zachowanie przy zmianie modułu. Problem leży w dyrektywach SetHandler wewnątrz konfiguracji modułu PHP.

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

Proszę zakomentować linie:

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

Końcowy plik php8.3.conf po poprawkach:

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>

Po edycji proszę zrestartować Apache:

1
sudo systemctl restart apache2

Wideo: czym jest Grav CMS i od czego zacząć

Krótkie wprowadzenie do Grav dla osób, które pierwszy raz słyszą o flat-file CMS: co jest pod maską, jak zorganizowana jest treść i dlaczego bez bazy danych może być szybciej.

⁉️🤔 Często zadawane pytania

Czy Grav potrzebuje bazy danych?

Nie, Grav to flat-file CMS. Cała treść, ustawienia, taksonomie i metadane są przechowywane w plikach tekstowych (Markdown i YAML). SQLite jest używane opcjonalnie do celów wewnętrznych: cache wtyczek, logi, kolejki. PostgreSQL i MySQL nie są oficjalnie wymagane. W praktyce oznacza to, że kopia zapasowa strony to po prostu kopia katalogu /user.

Czy wtyczka Page Toc jest obowiązkowa do generowania spisu treści?

Można ją zastąpić bezpośrednim kodem Twig z toc(page.content) w szablonie motywu. Jednak wtyczka jest wygodniejsza do szybkiego włączania/wyłączania za pomocą flagi w YAML-owym frontmatterze konkretnej strony. Jeśli na stronie jest ponad 50 podstron, zarządzanie przez header jest praktyczniejsze niż rozgałęzianie logiki w szablonie.

Czym Highlight różni się od Prism.js lub Highlight.js?

Highlight to oficjalna wtyczka Grav, która integruje highlight.js bezpośrednio w potoku renderowania. Rozumie flagi enabled i lines z YAML-owego headera i nie wymaga ręcznego podłączania JS/CSS, wszystko robi GPM. Prism.js trzeba podłączyć ręcznie w motywie.

Czy Grav jest nadal aktualny w 2026 roku w porównaniu z WordPress?

Dla pewnych scenariuszy tak. Grav wygrywa na statycznych wizytówkach, portfolio, dokumentacji i landing page'ach, gdzie nie jest potrzebna złożona logika użytkowników ani e-commerce. Architektura flat-file zapewnia natychmiastową responsywność bez bazy danych, a kontrolę wersji treści przez Git. Jednak dla bloga z tysiącami wpisów, mediateką i dynamicznymi archiwami WordPress jest praktyczniejszy dzięki ekosystemowi wtyczek.

Co zrobić, jeśli po aktualizacji PHP przestał działać panel administracyjny Grav?

Trzy typowe przyczyny: (1) nie zainstalowano php8.x-sqlite, Grav cicho pada bez sterownika BD; (2) nie zakomentowano SetHandler w php8.x.conf podczas korzystania z Virtualmin, Apache serwuje .php jako tekst; (3) uprawnienia do katalogów cache/, logs/ i backup/ wewnątrz /user zostały zresetowane, należy wykonać chown -R www-data:www-data user/.

Gotowa ściągawka: co skopiować do projektu

Sześć plików i wtyczek, od których zaczyna się typowy projekt Grav na VPS: header z taksonomiami i page-toc, spis treści w Twig w szablonie, preprocesor Markdown, Highlight, Unitegallery oraz wyrażenia regularne Atom do postprocessingu eksportów. Dodaj opakowanie serwerowe z sekcji Ubuntu 24.04, a otrzymasz w pełni gotowe środowisko w pół godziny. Dodaj tę stronę do zakładek, aktualizujemy snippety pod kątem bieżących wersji Grav i PHP.