Configuration

All Grav configuration files are written in YAML syntax with a .yaml file extension. YAML is very intuitive which makes it very easy to both read and write, however, you can check out the YAML page in the Advanced chapter to get a complete understanding of the syntax available.

System Configuration

Grav focuses on making things as easy as possible for the user, and the same goes for configuration. Grav comes with some sensible default options, and these are contained in a file that resides in the system/config/system.yaml file.

However, you should never change this file, instead any configuration changes you need to make should be stored in a file called user/config/system.yaml. Any setting in this file with the same structure and naming will override the setting provided in the default system configuration file.

Here are the variables found in the default system/config/system.yaml file:

Basic Options

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

These configuration options do not appear within their own child sections. They're general options that affect the way the site operates, its timezone, and base URL.

Languages

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: {}

The Languages area of the file establishes the site's language settings. This includes which language(s) are supported, designation of the default language in the URLs, and translations. Here is the breakdown for the Languages area of the system configuration file:

Home

home:
  alias: '/home'
  hide_in_urls: false

The Home section is where you set the default route to the site's homepage. You can also choose to hide the home route in URLs.

Pages

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']

The Pages section of the system/config/system.yaml file is where you set a lot of the main theme-related settings. For example, this is where you set the theme used to render the site, page ordering, twig and markdown processing defaults, and more. This is where most of the decisions that affect the way your pages are rendered are made.

Cache

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:

The Cache section is where you can configure the site's caching settings. You can enable, disable, choose the method, and more.

Twig

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

The Twig section gives you a quick set of tools with which to configure Twig on your site for debugging, caching, and optimization.

Assets

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

The Assets section enables you to configure options related to the Assets Manager (JS, CSS).

Errors

errors:
  display: 0
  log: true

The Errors section determines how Grav handles error display and logging.

Log

log:
  handler: file
  syslog:
    facility: local6

The Log section allows you to configure alternate logging capabilities for Grav.

Debugger

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

The Debugger section gives you the ability to activate Grav's debugger. A useful tool during development.

Images

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

The Images section gives you the ability to set the default image quality images are resampled to, as well as to control image caching and debugging features.

Media

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

The Media section handles the configuration options for settings related to the handling of media files. This includes timestamp display, upload size, and more.

Session

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

These options determine session properties for your site.

GPM

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

Options in the GPM section control Grav's GPM (Grav Package Manager). For example, you can restrict GPM to using official sources and select the method GPM uses to retrieve packages. You can also choose between stable and testing releases, as well as set up a proxy URL.

Accounts

accounts:
  type: regular
  storage: file

Accounts settings allows you to try out the new experimental Flex Users. This basically means that Users are stored as Flex objects allowing more power and performance.

Flex

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

Flex Objects cache configuration settings are new in Grav 1.7. These are default settings for all Flex types, but they can be overridden for each Flex Directory.

Strict Mode

strict_mode:
  yaml_compat: true
  twig_compat: true
  blueprint_compat: false

Strict mode allows for a cleaner migration to future versions of Grav by moving to the newer versions of YAML and Twig processors. These may not be compatible with all 3rd party extensions.

Site Configuration

As well as the system.yaml file, Grav also provides a default site.yaml configuration file that is used to set some front-end specific configuration such as author name, author email, as well as some key taxonomy settings. You can override these in the same way as you would the system.yaml by providing your own configuration file in user/config/site.yaml. You can also use this file to put in arbitrary configuration options that you may want to reference from your content or templates.

The default system/config/site.yaml file that ships with Grav looks something like this:

title: Grav                                 # Name of the site
default_lang: en                            # Default language for site (potentially used by theme)

author:
  name: John Appleseed                      # Default author name
  email: '[email protected]'                 # Default author email

taxonomies: [category,tag]                  # Arbitrary list of taxonomy types

metadata:
  description: 'My Grav Site'               # Site description

summary:
  enabled: true                             # enable or disable summary of page
  format: short                             # long = summary delimiter will be ignored; short = use the first occurrence of delimiter or size
  size: 300                                 # Maximum length of summary (characters)
  delimiter: ===                            # The summary 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'      # Alias for /blog/sample-3
#  '/new/(.*)': '/blog/$1'                  # Regex any /new/my-page URL to /blog/my-page Route

blog:
  route: '/blog'                            # Custom value added (accessible via site.blog.route)

#menu:                                      # Menu Example
#    - text: Source
#      icon: github
#      url: https://github.com/getgrav/grav
#    - icon: twitter
#      url: http://twitter.com/getgrav

Let's break down the elements of this sample file:

Security

For increased security there is system/config/security.yaml file that sets some sensible defaults and is used by the Admin plugin when Saving content, as well in the new Reports section of Tools.

The default configuration looks like this:

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

If you wish to make any changes to these settings, you should copy this file to user/config/security.yaml and make edits there.

Other Configuration Settings and Files

User configuration is completely optional. You can override as little or as much of the default settings as you need. This applies to both the system, site, and any plugin configurations in your site.

You are also not limited to the user/config/system.yaml or the user/config/site.yaml files as described above. You can create any arbitrary .yaml configuration file in the user/config folder you wish and it will get picked up by Grav automatically.

As an example if the new configuration file is named user/config/data.yaml and a yaml variable in this file is called count:

count: 39

The variable would be accessed in your Twig template by using the following syntax:

{{ config.data.count }}

It would also be accessible via PHP from any plugin with the code:

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

Config Variable Namespacing

Paths to the configuration files will be used as a namespace for your configuration options.

Alternatively, you can put all the options into one file and use YAML structures to specify the hierarchy for your configuration options. This namespacing is built from a combination of the path + filename + option name.

For example: An option such as author: Frank Smith in file plugins/myplugin.yaml could be accessible via: plugins.myplugin.author. However, you could also have a plugins.yaml file and in that file have an option name called myplugin: author: Frank Smith and it would still be reachable by the same plugins.myplugin.author namespace.

Some example configuration files could be structured:

Plugins Configuration

Most plugins will come with their own YAML configuration file. We recommend copying this file to the user/config/plugins/ directory rather than editing configuration options directly to the file located in the plugin's directory. Doing this will ensure that an update to the plugin will not overwrite your settings, and keep all of your configurable options in one, convenient place.

If you have a plugin called user/plugins/myplugin that has a configuration file called user/plugins/myplugin/myplugin.yaml then you would copy this file to user/config/plugins/myplugin.yaml and edit the file there.

The YAML file that exists within the plugin's primary directory will act as a fallback. Any settings listed there and not in the User folder's copy will be picked up and used by Grav.

Themes Configuration

The same rules for themes apply as they did for plugins. So if you have a theme called user/themes/mytheme that has a configuration file called user/themes/mytheme/mytheme.yaml then you would copy this file to user/config/themes/mytheme.yaml and edit the file there.