Когда работаешь с 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.