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

 1absolute_urls: false
 2timezone: ''
 3default_locale:
 4param_sep: ':'
 5wrapped_site: false
 6reverse_proxy_setup: false
 7force_ssl: false
 8force_lowercase_urls: true
 9custom_base_url: ''
10username_regex: '^[a-z0-9_-]{3,16}$'
11pwd_regex: '(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8,}'
12intl_enabled: true
13http_x_forwarded:
14  protocol: true
15  host: false
16  port: true
17  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

 1languages:
 2  supported: []
 3  default_lang:
 4  include_default_lang: true
 5  include_default_lang_file_extension: true
 6  pages_fallback_only: false
 7  translations: true
 8  translations_fallback: true
 9  session_store_active: false
10  http_accept_language: false
11  override_locale: false
12  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

 1home:
 2  alias: '/home'
 3  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

 1pages:
 2  type: regular
 3  theme: quark
 4  order:
 5    by: default
 6    dir: asc
 7  list:
 8    count: 20
 9  dateformat:
10    default:
11    short: 'jS M Y'
12    long: 'F jS \a\t g:ia'
13  publish_dates: true
14  process:
15    markdown: true
16    twig: false
17  twig_first: false
18  never_cache_twig: false
19  events:
20    page: true
21    twig: true
22  markdown:
23    extra: false
24    auto_line_breaks: false
25    auto_url_links: false
26    escape_markup: false
27    special_chars:
28      '>': 'gt'
29      '<': 'lt'
30    valid_link_attributes:
31      - rel
32      - target
33      - id
34      - class
35      - classes
36  types: [html,htm,xml,txt,json,rss,atom]
37  append_url_extension: ''
38  expires: 604800
39  cache_control:
40  last_modified: false
41  etag: false
42  vary_accept_encoding: false
43  redirect_default_route: false
44  redirect_default_code: 302
45  redirect_trailing_slash: true
46  ignore_files: [.DS_Store]
47  ignore_folders: [.git, .idea]
48  ignore_hidden: true
49  hide_empty_folders: false
50  url_taxonomy_filters: true
51  frontmatter:
52    process_twig: false
53    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

 1cache:
 2  enabled: true
 3  check:
 4    method: file
 5  driver: auto
 6  prefix: 'g'
 7  purge_at: '0 4 * * *'
 8  clear_at: '0 3 * * *'
 9  clear_job_type: 'standard'
10  clear_images_by_default: false
11  cli_compatibility: false
12  lifetime: 604800
13  gzip: false
14  allow_webserver_gzip: false
15  redis:
16    socket: false
17    password:
18    database:

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

Twig

 1twig:
 2  cache: true
 3  debug: true
 4  auto_reload: true
 5  autoescape: false
 6  undefined_functions: true
 7  undefined_filters: true
 8  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

 1assets:
 2  css_pipeline: false
 3  css_pipeline_include_externals: true
 4  css_pipeline_before_excludes: true
 5  css_minify: true
 6  css_minify_windows: false
 7  css_rewrite: true
 8  js_pipeline: false
 9  js_pipeline_include_externals: true
10  js_pipeline_before_excludes: true
11  js_module_pipeline: false
12  js_module_pipeline_include_externals: true
13  js_module_pipeline_before_excludes: true
14  js_minify: true
15  enable_asset_timestamp: false
16  enable_asset_sri: false
17  collections:
18    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

 1errors:
 2  display: 0
 3  log: true

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

Log

 1log:
 2  handler: file
 3  syslog:
 4    facility: local6

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

Debugger

 1debugger:
 2  enabled: false
 3  provider: clockwork
 4  censored: false
 5  shutdown:
 6    close_connection: true

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

Images

 1images:
 2  default_image_quality: 85
 3  cache_all: false
 4  cache_perms: '0755'
 5  debug: false
 6  auto_fix_orientation: false
 7  seofriendly: false
 8  cls:
 9    auto_sizes: false
10    aspect_ratio: false
11    retina_scale: 1
12  defaults:
13    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

 1media:
 2  enable_media_timestamp: false
 3  unsupported_inline_types: []
 4  allowed_fallback_types: []
 5  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

 1session:
 2  enabled: true
 3  initialize: true
 4  timeout: 1800
 5  name: grav-site
 6  uniqueness: path
 7  secure: false
 8  httponly: true
 9  samesite: Lax
10  split: true
11  domain:
12  path:

These options determine session properties for your site.

GPM

 1gpm:
 2  releases: stable
 3  proxy_url:
 4  method: 'auto'
 5  verify_peer: true
 6  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

 1accounts:
 2  type: regular
 3  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

 1flex:
 2  cache:
 3    index:
 4      enabled: true
 5      lifetime: 60
 6    object:
 7      enabled: true
 8      lifetime: 600
 9    render:
10      enabled: true
11      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

 1strict_mode:
 2  yaml_compat: true
 3  twig_compat: true
 4  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:

 1title: Grav                                 # Name of the site
 2default_lang: en                            # Default language for site (potentially used by theme)
 3
 4author:
 5  name: John Appleseed                      # Default author name
 6  email: '[email protected]'                 # Default author email
 7
 8taxonomies: [category,tag]                  # Arbitrary list of taxonomy types
 9
10metadata:
11  description: 'My Grav Site'               # Site description
12
13summary:
14  enabled: true                             # enable or disable summary of page
15  format: short                             # long = summary delimiter will be ignored; short = use the first occurrence of delimiter or size
16  size: 300                                 # Maximum length of summary (characters)
17  delimiter: ===                            # The summary delimiter
18
19redirects:
20#  '/redirect-test': '/'                    # Redirect test goes to home page
21#  '/old/(.*)': '/new/$1'                   # Would redirect /old/my-page to /new/my-page
22
23routes:
24#  '/something/else': '/blog/sample-3'      # Alias for /blog/sample-3
25#  '/new/(.*)': '/blog/$1'                  # Regex any /new/my-page URL to /blog/my-page Route
26
27blog:
28  route: '/blog'                            # Custom value added (accessible via site.blog.route)
29
30#menu:                                      # Menu Example
31#    - text: Source
32#      icon: github
33#      url: https://github.com/getgrav/grav
34#    - icon: twitter
35#      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:

 1xss_whitelist: [admin.super]
 2xss_enabled:
 3    on_events: true
 4    invalid_protocols: true
 5    moz_binding: true
 6    html_inline_styles: true
 7    dangerous_tags: true
 8xss_invalid_protocols:
 9    - javascript
10    - livescript
11    - vbscript
12    - mocha
13    - feed
14    - data
15xss_dangerous_tags:
16    - applet
17    - meta
18    - xml
19    - blink
20    - link
21    - style
22    - script
23    - embed
24    - object
25    - iframe
26    - frame
27    - frameset
28    - ilayer
29    - layer
30    - bgsound
31    - title
32    - base
33uploads_dangerous_extensions:
34    - php
35    - html
36    - htm
37    - js
38    - exe
39sanitize_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.