Коли працюєш із Grav CMS не перший рік, накопичується набір сніпетів, які кочують із проєкту в проєкт. YAML-фронтметтер, Twig-шаблони, конфіги підсвічування синтаксису, регулярки для Atom, щоразу лізти в документацію чи старий репозиторій — це марнування часу. Особливо якщо Grav стоїть на VPS і треба згадати, як правильно встановити sqlite-драйвер під PHP 8.3 або закоментувати SetHandler після оновлення Apache.

Ця шпаргалка, витяг із реальної практики: header за замовчуванням, Markdown-налаштування для сторінок, Twig-сніпети в тілі запису, Atom-регулярки для постобробки.md-експортів і серверні команди Ubuntu. Усе в одному місці, з поясненнями що й навіщо.

💡 Швидкий огляд:

• Налаштувати YAML-фронтметтер Grav з усіма полями: taxonomy, page-toc, highlight, process, кастомні page-addon
• Прописати Markdown-логіку в header сторінок: title, description, дата, таксономії, шаблон
• Додати Twig-код у тіло: авто-зміст через toc(), галерея Unitegallery
• Обробити.md-експорти Writage в Atom: заміна media/ у шляхах, прокидання класів для lazy load
• Підняти серверне оточення: SQLite, Memcached, PHP 8.3 на Ubuntu 24.04, правка php*.conf під Virtualmin

Grav, header за замовчуванням для всіх сторінок сайту

Базовий YAML-фронтметтер Grav-сторінки містить поля, які CMS читає під час рендерингу. Нижче, робочий шаблон, що покриває більшість типових задач: від таксономій до кастомних прапорців 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 активує плагін Page Toc (GitHub), він будує зміст за H1-H6 прямо на сторінці. template: blog_item жорстко задає шаблон дочірньої сторінки блогу, щоб Grav не визначав його евристично під час кожного рендеру.

Блок page-addon, кастомний розділ для користувацьких прапорців. Тут ifarmelazy: true вмикає ледаче завантаження iframe: у файлі user/themes/g5_helium/custom/templates/partials/blog_item.html.twig спрацьовує умова, що підключає скрипт 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

Для вставки самого iframe (наприклад, YouTube-відео) використовується конструкція:

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-налаштування, заголовки сторінок записів

Секція відповідає за поля, які прописуються в header кожного конкретного запису.

Title і Description

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

Description потрапляє в <meta name="description"> і важливий для сніпета в пошуковій видачі.

Дата створення та Auto Date

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

Щоб дата проставлялася автоматично під час створення сторінки, встановіть плагін Auto Date, github.com/getgrav/grav-plugin-auto-date. Він підставляє поточні дату й час, якщо поле date не заповнене вручну.

Таксономії

Для однієї категорії й одного тегу, плаский синтаксис:

1
taxonomy:
2
    category: WEB
3
    tag: Markdown

Для кількох значень, списком:

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

Page Toc і шаблон

Page Toc генерує зміст за заголовками всередині тіла сторінки. Крім прапорця page-toc.active: true у header, можна додати Twig-код прямо в шаблон теми (див. секцію Twig нижче).

template: blog_item прописується вручну, щоб Grav гарантовано використовував шаблон дочірнього запису блогу, CMS іноді помиляється з автовизначенням для нових сторінок.

Препроцесори Markdown і Twig

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

twig_first: true означає, що Grav спершу обробить Twig-шаблонізатор, а потім Markdown. Порядок критичний, якщо в тілі сторінки є Twig-логіка, яка генерує Markdown-розмітку.

Підсвічування синтаксису (Highlight)

Залежить від плагіна Highlight, github.com/getgrav/grav-plugin-highlight.

1
highlight:
2
    enabled: true
3
    lines: true

lines: true додає нумерацію рядків у блоках коду з підсвічуванням.

Twig-налаштування для тіла сторінок

Автозміст через toc()

Page Toc може працювати не лише з header, а й через пряму вставку в шаблон теми. У файлі user/themes/g5_helium/custom/templates/partials/blog_item.html.twig пропишіть:

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

Twig-функція toc(page.content) парсить заголовки всередині page.content і повертає структуроване дерево. Умова перевіряє прапорець page-toc.active із header, так зміст можна вмикати й вимикати для окремих сторінок, не чіпаючи шаблон.

Галерея зображень через Unitegallery

Плагін Unitegallery, github.com/variar/grav-plugin-unitegallery додає в Grav галерею на базі JS-бібліотеки Unitegallery з кількома темами відображення.

Після встановлення через адмінку або GPM (Grav Package Manager) у тіло сторінки додається один рядок:

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

Він рендерить усі зображення, завантажені в медіаколекцію сторінки, у вигляді галереї.

Atom, пошук і заміна для.md-експортів Writage

Під час експорту WordPress-постів у Markdown через Writage шляхи до зображень містять префікс media/, а для ввімкнення лінивого завантаження потрібні класи figure-img і img-fluid. Ручне виправлення кожного URL безглузде, Atom із регулярними виразами робить це за секунду.

За ліниве завантаження відповідає плагін Lazy Image, github.com/unsaturated/grav-plugin-lazy-image.

Знайти (регулярний вираз):

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

Замінити, варіант із лайтбоксом (плагін FeatherLight):

1
$1$3)

Замінити, варіант лише з лінивим завантаженням:

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

Після заміни зображення отримує query-параметр classes, який підхоплює Lazy Image.

Робота з ескізами

Grav уміє динамічно маніпулювати зображеннями: ресайз, кроп, кешування. Ескіз сторінки задається через синтаксис Markdown із query-параметрами:

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

Докладніше про медіа-можливості, в офіційній документації: learn.getgrav.org/content/media.

Ubuntu 24.04, серверна обв'язка для Grav

Grav на VPS потребує PHP, SQLite (для внутрішньої БД плагінів) і бажано Memcached (кешування сторінок). Нижче, актуальні команди під Ubuntu 24.04 LTS і PHP 8.3.

Встановлення PDO SQLite на PHP 8.3

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

SQLite використовується Grav для зберігання логів, кешу плагінів і внутрішньої бухгалтерії. Без драйвера адмінка впаде з помилкою підключення до БД.

Встановлення Memcached

Актуальна інструкція: 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-файли не виконуються після зміни версії (Virtualmin/Webmin)

Після переходу з PHP 7.x на 8.3 Apache може віддавати .php-файли як текст замість виконання, відома поведінка при зміні модуля. Проблема в директивах SetHandler всередині конфігурації модуля PHP.

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

Закоментуйте рядки:

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

Підсумковий php8.3.conf після правок:

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>

Після редагування перезавантажте Apache:

1
sudo systemctl restart apache2

Відео: що таке Grav CMS і з чого почати

Короткий вступ до Grav для тих, хто вперше чує про flat-file CMS, що під капотом, як влаштований контент і чому без бази даних може бути швидше.

⁉️🤔 Часті запитання

Чи потрібна база даних для Grav?

Ні, Grav — це flat-file CMS. Весь контент, налаштування, таксономії та метадані зберігаються в текстових файлах (Markdown і YAML). SQLite використовується опціонально для внутрішніх потреб: кеш плагінів, логи, черги. PostgreSQL і MySQL офіційно не потрібні. На практиці це означає, що бекап сайту — це просто копія теки /user.

Чи обов'язковий плагін Page Toc для змісту?

Його можна замінити прямим Twig-кодом з toc(page.content) у шаблоні теми. Але плагін зручніший для швидкого ввімкнення/вимкнення через прапорець у YAML-фронтметтері конкретної сторінки. Якщо на сайті 50+ сторінок, керування через header практичніше, ніж розгалуження в шаблоні.

Чим Highlight відрізняється від Prism.js або Highlight.js?

Highlight — це офіційний Grav-плагін, який інтегрує highlight.js прямо в пайплайн рендерингу. Він розуміє прапорці enabled і lines з YAML-хедера і не потребує ручного підключення JS/CSS, усе робить GPM. Prism.js доведеться підключати вручну в темі.

Чи актуальний Grav у 2026 році порівняно з WordPress?

Для певних сценаріїв, так. Grav виграє на статичних сайтах-візитівках, портфоліо, документації та лендингах, де не потрібна складна логіка користувачів та e-commerce. Flat-file архітектура дає миттєвий відгук без бази даних, а контроль версій контенту, через Git. Але для блогу з тисячами дописів, медіатекою та динамічними архівами WordPress практичніший завдяки екосистемі плагінів.

Що робити, якщо після оновлення PHP перестала працювати адмінка Grav?

Три типові причини: (1) не встановлено php8.x-sqlite, Grav мовчки падає без драйвера БД; (2) не закоментовано SetHandler у php8.x.conf під час використання Virtualmin, Apache віддає .php як текст; (3) права на теки cache/, logs/ і backup/ всередині /user скинулися, виконайте chown -R www-data:www-data user/.

Готова шпаргалка: що копіювати в проєкт

Шість файлів і плагінів, з яких починається типовий Grav-проєкт на VPS: header з таксономіями та page-toc, Twig-зміст у шаблоні, Markdown-препроцесор, Highlight, Unitegallery та Atom-регулярки для постобробки експортів. Додайте серверну обв'язку з секції Ubuntu 24.04, і у вас повністю готове середовище за пів години. Тримайте цю сторінку в закладках, ми оновлюємо сніпети під актуальні версії Grav і PHP.