Настройка⚓︎

Все конфигурационные файлы Grav написаны с использованием синтаксиса YAML и имеют расширение .yaml. YAML очень интуитивно понятен, что делает его очень лёгким как для чтения, так и для записи, однако вы можете получить полное представление о доступном синтаксисе.

Системная конфигурация⚓︎

Grav фокусируется на том, чтобы максимально упростить работу для пользователя, и то же самое касается конфигурации. Grav поставляется с некоторыми разумными опциями по умолчанию, которые содержатся в файле system/config/system.yaml.

Однако вы никогда не должны изменять этот файл, вместо этого любые изменения конфигурации, которые вам нужно сделать, должны храниться в файле с именем user/config/system.yaml. Любая настройка в этом файле с такой же структурой и именами переопределяет настройку, заданную в файле конфигурации системы по умолчанию.

Вот переменные, заданные в файле system/config/system.yaml по умолчанию:

Основные параметры⚓︎

absolute_urls: false
timezone: ''
default_locale:
param_sep: ':'
wrapped_site: false
reverse_proxy_setup: false
force_ssl: false
force_lowercase_urls: true
custom_base_url: ''
username_regex: '^[a-z0-9_-]{3,16}$'
pwd_regex: '(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8,}'
intl_enabled: true
http_x_forwarded:
  protocol: true
  host: false
  port: true
  ip: true

Эти параметры конфигурации не отображаются в собственных дочерних разделах. Это общие параметры, которые влияют на работу сайта, его часовой пояс и базовый URL.

Языки⚓︎

languages:
  supported: []
  default_lang:
  include_default_lang: true
  include_default_lang_file_extension: true
  pages_fallback_only: false
  translations: true
  translations_fallback: true
  session_store_active: false
  http_accept_language: false
  override_locale: false
  content_fallback: {}

В секции Languages файла устанавливаются языковые настройки сайта. Вот разбивка для области Languages файла конфигурации системы:

Главная страница⚓︎

home:
  alias: '/home'
  hide_in_urls: false

В разделе Home задается маршрут по умолчанию к главной странице сайта. Вы также можете выбрать скрытие домашнего маршрута в URL-адресах.

Страницы⚓︎

pages:
  type: regular
  theme: quark
  order:
    by: default
    dir: asc
  list:
    count: 20
  dateformat:
    default:
    short: 'jS M Y'
    long: 'F jS \a\t g:ia'
  publish_dates: true
  process:
    markdown: true
    twig: false
  twig_first: false
  never_cache_twig: false
  events:
    page: true
    twig: true
  markdown:
    extra: false
    auto_line_breaks: false
    auto_url_links: false
    escape_markup: false
    special_chars:
      '>': 'gt'
      '<': 'lt'
    valid_link_attributes:
      - rel
      - target
      - id
      - class
      - classes
  types: [html, htm, xml, txt, json, rss, atom]
  append_url_extension: ''
  expires: 604800
  cache_control:
  last_modified: false
  etag: false
  vary_accept_encoding: false
  redirect_default_route: false
  redirect_default_code: 302
  redirect_trailing_slash: true
  ignore_files: [.DS_Store]
  ignore_folders: [.git, .idea]
  ignore_hidden: true
  hide_empty_folders: false
  url_taxonomy_filters: true
  frontmatter:
    process_twig: false
    ignore_fields: ['form', 'forms']

В секции Pages файла system/config/system.yaml хранится множество основных настроек, связанных с темой. Например, здесь вы устанавливаете шаблон, используемый для визуализации сайта, порядок страниц, параметры обработки Twig и Markdown по умолчанию, и многое другое. Именно здесь принимаются большинство решений, влияющих на способ визуализации ваших страниц.

Кэш⚓︎

cache:
  enabled: true
  check:
    method: file
  driver: auto
  prefix: 'g'
  purge_at: '0 4 * * *'
  clear_at: '0 3 * * *'
  clear_job_type: 'standard'
  clear_images_by_default: false
  cli_compatibility: false
  lifetime: 604800
  gzip: false
  allow_webserver_gzip: false
  redis:
    socket: false
    password:
    database:

В секции Cache можно настроить параметры кэширования сайта.

Twig⚓︎

twig:
  cache: true
  debug: true
  auto_reload: true
  autoescape: false
  undefined_functions: true
  undefined_filters: true
  umask_fix: false

В секции Twig к вашим услугам быстрый набор инструментов, с помощью которых на вашем сайте можно настроить Twig для отладки, кэширования и оптимизации.

Активы⚓︎

assets:
  css_pipeline: false
  css_pipeline_include_externals: true
  css_pipeline_before_excludes: true
  css_minify: true
  css_minify_windows: false
  css_rewrite: true
  js_pipeline: false
  js_pipeline_include_externals: true
  js_pipeline_before_excludes: true
  js_module_pipeline: false
  js_module_pipeline_include_externals: true
  js_module_pipeline_before_excludes: true
  js_minify: true
  enable_asset_timestamp: false
  enable_asset_sri: false
  collections:
    jquery: system://assets/jquery/jquery-2.x.min.js

В секции Assets можно настроить параметры, связанные с менеджером активов (JS, CSS).

Ошибки⚓︎

errors:
  display: 0
  log: true

В секции Errors настраивается отображение и ведение журнала ошибок Grav.

Лог⚓︎

log:
  handler: file
  syslog:
    facility: local6

В секции Log можно настроить альтернативные возможности ведения журнала для Grav.

Отладчик⚓︎

debugger:
  enabled: false
  provider: clockwork
  censored: false
  shutdown:
    close_connection: true

В секции Debugger можно активировать отладчик Grav. Полезный инструмент во время разработки.

Изображения⚓︎

images:
  default_image_quality: 85
  cache_all: false
  cache_perms: '0755'
  debug: false
  auto_fix_orientation: false
  seofriendly: false
  cls:
    auto_sizes: false
    aspect_ratio: false
    retina_scale: 1
  defaults:
    loading: auto

В секции Images можно задать качество изображений по умолчанию, на которое будут пересчитываться изображения, а также управлять функциями кэширования изображений и отладки.

Медиа⚓︎

media:
  enable_media_timestamp: false
  unsupported_inline_types: []
  allowed_fallback_types: []
  auto_metadata_exif: false

В секции Media задаются параметры конфигурации, связанные с обработкой медиафайлов. Это включает в себя отображение временных меток, размер загружаемых файлов и многое другое.

Сессия⚓︎

session:
  enabled: true
  initialize: true
  timeout: 1800
  name: grav-site
  uniqueness: path
  secure: false
  httponly: true
  samesite: Lax
  split: true
  domain:
  path:

Эти параметры определяют свойства сеанса для вашего сайта.

GPM⚓︎

gpm:
  releases: stable
  proxy_url:
  method: 'auto'
  verify_peer: true
  official_gpm_only: true

Параметры в секции GPM контролируют менеджер пакетов Grav. Например, вы можете ограничить GPM использованием официальных источников и выбрать метод, используемый GPM для извлечения пакетов. Вы также можете выбрать между стабильными и тестовыми выпусками, а также настроить URL-адрес прокси-сервера.

Учётные записи⚓︎

accounts:
  type: regular
  storage: file

Настройки учётных записей позволяют вам опробовать новых экспериментальных flex-пользователей. Это в основном означает, что пользователи хранятся в виде flex-объектов, обеспечивающих большую мощность и производительность.

Flex⚓︎

flex:
  cache:
    index:
      enabled: true
      lifetime: 60
    object:
      enabled: true
      lifetime: 600
    render:
      enabled: true
      lifetime: 600

Параметры конфигурации кэша объектов Flex являются новыми в Grav 1.7. Это настройки по умолчанию для всех типов Flex, но их можно переопределить для каждой Flex-директории.

Строгий режим⚓︎

strict_mode:
  yaml_compat: true
  twig_compat: true
  blueprint_compat: false

Строгий режим позволяет более чистую миграцию в будущие версии Grav, Перейдя на более новые версии процессоров YAML и Twig. Они могут быть несовместимы со всеми сторонними расширениями.

Настройка сайта⚓︎

Наряду с файлом system.yaml, Grav также предоставляет файл конфигурации по умолчанию site.yaml, который используется для установки некоторых специфических интерфейсных настроек, таких как имя автора, адрес электронной почты автора, а также некоторые ключевые параметры таксономии. Вы можете переопределить их так же, как и system.yaml, предоставив свой собственный файл конфигурации в user/config/site.yaml. Вы также можете использовать этот файл для добавления произвольных параметров конфигурации, на которые вы можете ссылаться из вашего контента или шаблонов.

Файл system/config/site.yaml по умолчанию, который поставляется с Grav, выглядит примерно так:

title: Grav # Название сайта
default_lang: en # Язык сайта (потенциально используется шаблоном)

author:
  name: John Appleseed # Имя автора по умолчанию
  email: 'john@example.com' # Имейл автора по умолчанию

taxonomies: [category, tag] # Произвольный список типов таксономии

metadata:
  description: 'My Grav Site' # Описание сайта

summary:
  enabled: true # включить или отключить тизер страницы
  format: short # long = разделитель тизера будет проигнорирован; short = используйте первое вхождение разделителя или размер
  size: 300 # Максимальная длина тизера (в символах)
  delimiter: === # Разделитель тизера

redirects:
#  '/redirect-test': '/'                    # Redirect test goes to home page
#  '/old/(.*)': '/new/$1'                   # Would redirect /old/my-page to /new/my-page

routes:
#  '/something/else': '/blog/sample-3'      # Алиас для /blog/sample-3
#  '/new/(.*)': '/blog/$1'                  # Регулярное выражение для редиректа любого адреса вида /new/my-page на /blog/my-page

blog:
  route: '/blog' # Пользовательское значение (доступно по адресу site.blog.route)

#menu:                                      # Пример меню
#    - text: Source
#      icon: github
#      url: https://github.com/getgrav/grav
#    - icon: twitter
#      url: http://twitter.com/getgrav

Давайте разберем элементы этого примера файла:

Безопасность⚓︎

Для повышенной безопасности есть файл system/config/security.yaml, который устанавливает некоторые разумные значения по умолчанию и используется плагином админки, когда сохраняется контент, а также в новом разделе Отчёты.

Конфигурация по умолчанию выглядит следующим образом:

xss_whitelist: [admin.super]
xss_enabled:
  on_events: true
  invalid_protocols: true
  moz_binding: true
  html_inline_styles: true
  dangerous_tags: true
xss_invalid_protocols:
  - javascript
  - livescript
  - vbscript
  - mocha
  - feed
  - data
xss_dangerous_tags:
  - applet
  - meta
  - xml
  - blink
  - link
  - style
  - script
  - embed
  - object
  - iframe
  - frame
  - frameset
  - ilayer
  - layer
  - bgsound
  - title
  - base
uploads_dangerous_extensions:
  - php
  - html
  - htm
  - js
  - exe
sanitize_svg: true

Если вы хотите внести какие-либо изменения в эти настройки, вам следует скопировать этот файл в user/config/security.yaml и внести туда правки.

Другие параметры конфигурации и файлы⚓︎

Конфигурация пользователя полностью необязательна. Вы можете переопределить так мало или так много настроек по умолчанию, как вам нужно. Это относится как к системе, сайту, так и к любым конфигурациям плагинов на вашем сайте.

Вы также не ограничены рамками файлов user/config/system.yaml или user/config/site.yaml, как описано выше. Вы можете создать любой произвольный файл конфигурации .yaml в директории user/config, и он будет автоматически подхвачен Grav.

Например, если новый конфигурационный файл имеет имя user/config/data.yaml и переменная yaml в этом файле называется count:

count: 39

Доступ к переменной будет осуществляться в вашем шаблоне Twig с помощью следующего синтаксиса:

{{ config.data.count }}

Он также будет доступен через PHP из любого плагина через код:

$count_var = Grav::instance()['config']->get('data.count');

Пространство имен переменных конфигурации⚓︎

Пути к файлам конфигурации будут использоваться в качестве пространства имен для ваших параметров конфигурации.

Кроме того, вы можете поместить все параметры в один файл и использовать структуры YAML, чтобы указать иерархию для параметров конфигурации. Это пространство имен построено из комбинации путь + имя файла + имя опции.

Например: такая опция, как author: Frank Smith в файле plugins/myplugin.yaml, может быть доступна через: plugins.myplugin.author. Однако у вас также может быть файл plugins.yaml, и в этом файле есть имя параметра с именем myplugin: author: Frank Smith, и оно всё равно будет доступно через то же пространство имен plugins.myplugin.author. Некоторые примеры файлов конфигурации могут быть структурированы:

Конфигурация плагинов⚓︎

Большинство плагинов будут поставляться с собственным файлом конфигурации YAML. Мы рекомендуем копировать этот файл в каталог user/config/plugins/, а не редактировать параметры конфигурации непосредственно в файле, расположенном в каталоге плагина. Это гарантирует, что обновление плагина не перезапишет ваши настройки и сохранит все ваши настраиваемые параметры в одном удобном месте.

Если у вас есть плагин с именем user/plugins/myplugin, который имеет файл конфигурации с именем user/plugins/myplugin/myplugin.yaml, то вы должны скопировать этот файл в user/config/plugins/myplugin.yaml и отредактировать файл там.

Файл YAML, который существует в основном каталоге плагина, будет действовать как запасной вариант. Любые настройки, перечисленные там, а не в копии папки пользователя, будут подобраны и использованы Grav.

Конфигурация тем⚓︎

Для тем применяются те же правила, что и для плагинов. Так что если у вас есть тема с именем user/themes/mytheme, в которой есть файл конфигурации с именем user/themes/mytheme/mytheme.yaml, то вы должны скопировать этот файл в user/config/themes/mytheme.yaml и редактировать настройки там.