Все конфигурационные файлы Grav написаны с помощью синтаксиса YAML и имеют расширение .yaml. YAML очень интуитивен, что делает его простым как для чтения, так и для написания.
Конфигурация системы
Grav старается сделать всё настолько просто, насколько это возможно для пользователя, и это также относится к конфигурации. По умолчанию у Grav довольно разумный набор настроек, который находится в файле system/config/system.yaml
Однако вы никогда не должны менять этот файл. Если вы хотите внести изменения в конфигурацию, то сохраняйте настройки в файле user/config/system.yaml. Любая настройка в этом файле с такой же структурой и названием переопределит настройку, которая есть в файле конфигурации по умолчанию.
Строго говоря, вы никогда не должны менять что-то в папке system/. Всё, что делает пользователь (создает контент, устанавливает плагины, редактирует настройки и т.п.), должно быть сделано в папке user/. Это позволяет более просто обновляться, а также хранить все ваши изменения в одном месте для бэкапа, синхронизации и т.д.
Вот как выглядит дефолтный файл system/config/system.yaml:
absolute_urls: false # Абсолютные или относительные URL для `base_url`
timezone: '' # Временная зона. Валидные значения: http://php.net/manual/ru/timezones.php
default_locale: # Дефолтная локаль (по умолчанию системная)
param_sep: ':' # Разделитель параметров, используйте ';' в Apache на Windows
wrapped_site: false # Обёрнута ли Grav в другую платформу (необходимо для тем/плагинов)
languages:
supported: [] # Список поддерживаемых языков, например: [en, fr, de]
include_default_lang: true # Включить префикс дефолтного языка во все URL
translations: true # Включить переводы по умолчанию
translations_fallback: true # Откатываться на поддерживаемые языки, если активного языка не существует
session_store_active: false # Сохранять активный язык в сессии
http_accept_language: false # Пытаться установить язык, основываясь на заголовке http_accept_language в браузере
override_locale: false # Переопределить дефолтную или системную локаль на специфичную для языка
home:
alias: '/home' # Дефолтный путь для домашней страницы, например /
pages:
theme: antimatter # Дефолтная тема (по умолчанию "antimatter")
order:
by: default # Порядок страниц по "default" (умолчанию), "alpha" (алфавиту) or "date" (дате)
dir: asc # Дефолтное направление порядка "asc" (по возрастанию) или "desc" (по убыванию)
list:
count: 20 # Дефолтное количество элементов на страницу
dateformat:
default: # Дефолтный формат даты, который Grav ожидает в поле `date: `
short: 'jS M Y' # Формат короткой даты
long: 'F jS \a\t g:ia' # Формат длинной даты
publish_dates: true # Автоматически публиковать/снимать с публикации, основываясь на датах
process:
markdown: true # Обрабатывать Markdown
twig: false # Обрабатывать Twig
events:
page: true # Включить события на уровне страниц
twig: true # Включить события на уровне Twig
markdown:
extra: false # Включить поддежку Markdown Extra (по умолчанию GFM)
auto_line_breaks: false # Включить автоматический перенос строк
auto_url_links: false # Включить автоматические HTML ссылки
escape_markup: false # Экранировать теги разметки в сущности
special_chars: # Список специальных символов, которые следует автоматически конвертировать в сущности
'>': 'gt'
'<': 'lt'
types: [txt,xml,html,htm,json,rss,atom] # Список валидных типов страниц
append_url_extension: '' # Добавлять расширение к URL страниц (например, добавление '.html' - /path/page.html)
expires: 604800 # Истечение страницы в секундах (604800 секунд = 7 дней)
last_modified: false # Установить заголовок last modified date, основываясь на временной метке изменения файла
etag: false # Установить тег etag заголовка
vary_accept_encoding: false # Добавлять заголовок `Vary: Accept-Encoding`
redirect_default_route: false # Автоматически перенаправлять на дефолтный роут страницы
redirect_default_code: 301 # Дефолтный код для перенаправлений
redirect_trailing_slash: true # Обрабатывать автоматически или делать 301 редирект слеша / в URL
ignore_files: [.DS_Store] # Файлы, которые игнорировать в страницах
ignore_folders: [.git, .idea] # Папки, которые игнорировать в страницах
ignore_hidden: true # Игнорировать все скрытые файлы и папки
url_taxonomy_filters: true # Включить для коллекций страниц авто-магические фильтры таксономий, основанные на URL
cache:
enabled: true # Установите в true для включения кэшировния
check:
method: file # Метод проверки обновлений страниц: file|folder|none
driver: auto # Драйвер: auto|file|apc|xcache|memcache|wincache
prefix: 'g' # Префикс строки кэша (предотвращает конфликты кэша)
lifetime: 604800 # Время жизни кэша в секундах (0 = бесконечно)
gzip: false # Сжимать выходные данные страницы с помощью GZip
twig:
cache: true # Установите в true для включения кэширования Twig
debug: false # Включить отладку Twig
auto_reload: true # Обновлять кэш при изменениях
autoescape: false # Автоэкранирование переменных Twig
undefined_functions: true # Разрешить неопределённые функции
undefined_filters: true # Разрешить неопределённые фильтры
umask_fix: false # По умолчанию Twig создаёт файлы кэш как 755, фикс делает их 775
assets: # Настройка менеджера ассетов (JS, CSS)
css_pipeline: false # CSS конвейер - это объединение нескольких CSS ресурсов в один файл
css_minify: true # Минимизировать CSS во время объединения
css_minify_windows: false # Переопределение минимизации для Windows платформ. По умолчанию false из-за ThreadStackSize
css_rewrite: true # Перезаписать любые относительные URL во время объединения
js_pipeline: false # JS конвейер - это объединение нескольких JS ресурсов в один файл
js_minify: true # Минимизировать JS во время объединения
enable_asset_timestamp: false # Включить метку времени для ассетов
collections:
jquery: system://assets/jquery/jquery-2.1.4.min.js
errors:
display: false # Отображать полную backtrace страницу ошибки
log: true # Логировать ошибки в папку /logs
debugger:
enabled: false # Включить отладичк Grav
shutdown:
close_connection: true # Закрывать соединение перед вызовом onShutdown(). false при отладке
images:
default_image_quality: 85 # Дефолтное качество изображений при ресэмплировании (85%)
cache_all: false # Кэшировать все изображения
debug: false # Показывать оверлэй, который отображает глубину пикселей, например при работе с ретина дисплеями
media:
enable_media_timestamp: false # Включить метку времени для медиа
upload_limit: 0 # Максимальный размер загрузок в байтах (0 - неограничено)
unsupported_inline_types: [] # Массив типов медиа, которые пробовать отображать inline
allowed_fallback_types: [] # Массив разрешенных медиа типов файлов, если к ним получен доступ через роут страницы
session:
enabled: true # Включить поддержку сессии
timeout: 1800 # Таймаут в секундах
name: grav-site # Префикс для имени куки сессии. Используйте буквы, числа, тире или нижнее подчёркивание. Не используйте точку в имени сессии
Для переопределения вам не нужно копировать весть файл. Вы можете переопределить только то, что вам нужно. Просто убедитесь в том, что у вас такие же структура и название для настройки, которую вы хотите переопределить.
Конфигурация сайта
Также как и файл system.yaml, Grav предоставляет дефолтный файл конфигурации site.yaml, который используется для установки специфичных для фронт-энда настроек, таких как: имя автора, э-почта автора, а также некоторые ключевые настройки таксономии. Вы можете переопределить их также, как и для system.yaml, создав свой файл конфигурации в user/config/site.yaml. Вы также можете использовать этот файл для произвольных конфигурационных опций, к которым вы хотели бы обратиться из вашего контента или шаблонов.
Дефолтный файл system/config/site.yaml, который идёт в Grav, выглядит примерно так:
title: Grav # Название сайта
author:
name: John Appleseed # Дефолтное имя автора
email: 'john @ email.com' # Дефолтный e-mail автора
taxonomies: [category,tag] # Обязательный список типов таксономий
metadata:
description: 'My Grav Site' # Описание сайта
summary:
enabled: true # Включить вводный текст страницы
format: short # long = разделитель вводного текста будет игнорирован; short = использовать первое вхождение разделителя или размер (size)
size: 300 # Максимальная длина вводного текста (символы)
delimiter: === # Разделитель
redirects:
'/redirect-test': '/' # Перенаправит /redirect-test на главную
'/old/(.*)': '/new/$1' # Перенаправит /old/my-page на /new/my-page
routes:
'/something/else': '/blog/sample-3' # Алиас для /blog/sample-3
'/new/(.*)': '/blog/$1' # Regex любого /new/my-page URL на роут /blog/my-page
blog:
route: '/blog' # Своё значение (доступно через system.blog.route)
#menu: # Пример меню
# - text: Source
# icon: github
# url: https://github.com/getgrav/grav
# - icon: twitter
# url: http://twitter.com/getgrav
Давайте рассмотрим элементы этого файла:
| Поле | Описание |
|---|---|
| title: | Заголовок – это простая строковая переменная, которую необходимо установить тогда, когда вы хотите отобразить название сайта. |
| author: name: |
Имя автора сайта |
| author: email: |
Дефолтный email для использования на сайте |
| taxonomies: | Обязательный список высокоуровневых типов для организации вашего контента. Вы можете назначать контент конкретным типам таксономий, например категориям или тегам. Редактируйте по своему желанию. |
| metadata: | Установка мета-данных для всех ваших страниц |
| summary: size: |
Переменная, которая переопределяет дефолтное кол-во символов вводного текста. |
| routes: | Это базовая карта маппинга, которая предоставляет простые возможности алиаса в Grav. Если вы откроете в браузере /something/else вы будете перенаправлены на /blog/sample-3. Редактируйте по своему желанию. Поддерживаются Regex замены ((.*) - $1) в конце роута алиасов. Для оптимальной производительности они должны находится в конце списка. |
| (свои параметры) | Вы можете создать любой параметр по своему желанию. Хороший примером такого параметра является blog: route: '/blog', который доступен в ваших шаблонах Twig через system.blog.route |
Для большинства самым важным элементом в этом файле является список таксономий. Если вы хотите использовать таксономию в вашем контенте, то она должна быть определена именно здесь.
Другие настройки и файлы
Пользовательская настройка полностью необязательна. Вы можете переопределить только то, что необходимо. Это относится к настройкам системы, сайта и любых плагинов.
Вы также не ограничены файлами user/config/system.yaml или user/config/site.yaml. Вы можете создать любой произвольный файл конфигурации .yaml в папке user/config и он будет использован Grav автоматически.
Пути до файлов конфигурации будут использованы как пространство имён для ваших настроечных параметров.
Как вариант, вы можете указать все настройки в одном файле и использовать структуры YAML для указания иерархии для ваших параметров. Это пространство имён создается из комбинации путь + имя файла + название параметра.
Например, такой параметр как author: Frank Smith в файле plugins/myplugin.yaml может быть доступен через plugins.myplugin.author. Однако вы также можете иметь файл plugins.yaml, а в этом файле у вас может быть параметр myplugin: author: Frank Smith, и он также будет доступен с тем же пространством имён plugins.myplugin.author.
Вот некоторые примеры структурированных файлов конфигурации:
| Имя файла | Описание |
|---|---|
| user/config/system.yaml | Файл глобальных настроек системы |
| user/config/system.yaml | Файл настроек сайта |
| user/config/system.yaml | Файл индивидуальных настроек для плагина myplugin |
Файл конфигурации с пространством имён переопределит все параметры, которые имеют такой же путь в дефолтном файле конфигурации.
У большинства плагинов есть свой файл конфигурации YAML. Рекомендуется копировать этот файл в папку user/config/plugins/, а не редактировать его в папке плагинов. Это позволит сохранять ваши настройки при обновлении плагинов.
YAML файл, который существует в первичной директории плагина будет выступать в роли fallback. Любая указанная здесь настройка, которой нет в копии папки пользователя, будет подхвачена и использована Grav.
