Configuration

How to modify the behavior of Qgoda.

The Qgoda configuration is straightforward and has sane defaults. In fact, Qgoda runs without any configuration and you only have to configure Qgoda, when you want to change a certain behavior.

Configuration Files

Qgoda has two optional configuration files, _config.yaml and _localconfig.yaml. You can also use the file extension .yml if you prefer.

Qgoda Configuration Layers
The different configuration layers of Qgoda

The configuration found in _config.yaml overrides the built-in defaults, and the configuration found in _localconfig.yaml overrides both _config.yaml and the the built-in defaults.

More precisely, each layer of configuration is merged with the previous one and overrides only those parts that differ.

You can always check the actual configuration used with the command qgoda config which dumps the resulting configuration to the console.

Why _localconfig.yaml?

Qgoda, like most static site generators, works very well with git and you may want to publish the site sources to a public git repository.

But what if you have to put API keys, secrets, private information, local hostnames or local debugging settings into the configuration? In all these cases you can use _localconfig.yaml. You will normally not commit that file to the public repository but use it for local use only.

Accessing Configuration Variables From Templates

The entire configuration of the site is accessible in the template variable config:

<html>
  <head>
    <title>[% config.title | html %]
  </head>
  <body>
    <h1>[% config.title | html %]</h1>
    <div>[% asset.content %]</div>
  </body>
</html>

This is how you would access the configuration variable title from a template.

JSON Schema

In order to protect you against incorrect configurations, your settings are validated against a JSON schema. You can even see that schema with the command qgoda schema. Try qgoda schema --help for information about different output formats of the schema.

While writing a schema is not that trivial, reading it is relatively easy.

Implementation

Reading the configuration and validating it against the schema is done in JavaScript with Ajv, an advanced and fast validator. The Qgoda configuration schema complies to draft 07 of the JSON schema specification.

Defaults

The defaults for all configuration options are part of the schema.

Type Coercion

JSON schema is strict about data types. If an array is expected for a certain configuration variable it would normally be a mistake to give a string. But Qgoda uses type coercion and will automatically convert a single value into an array for you.

Likewise, a boolean option actually requires either true or false. With type coercion you can use 0, an empty string or null as an alias for false, and pretty much everything else is interpreted as true. See the complete table at https://github.com/epoberezkin/ajv/blob/master/COERCION.md for the complete story.

Program Paths

It is very often necessary to configure a path to a program in _config.yaml for example in helpers or po.xgettext or others. This is a special case where type coercion helps you to simplify the configuration.

Without Arguments

If the program does not take any arguments, you can pass it as a single string, for example:

helpers:
  assets: webpack

With Arguments

If the program should be invoked with arguments, use an array instead:

helpers:
  assets:
  - webpack
  - --progress
  - --colors
  - --watch

Or use this equivalent syntax for arrays:

helpers:
  assets: ['webpack', '--progress', '--colors', '--watch']

Adding Your Own Configuration Variables

You can add your own configuration variables to your heart's delight but not in slots already in use by Qgoda. For example, you cannot add a variable to paths. This is a meant as a protection against typos.

But you are free to define your own variables and use them in any way you want.

You have to keep in mind, though, that Qgoda may use more configuration variables in the future. You will normally notice that immediately because the configuration will no longer validate. But if you want to be 100 % on the safe side, put all configuration variables for local usage into the slot local which is guaranteed not to be used by Qgoda itself:

local:
  paths:
    images: _assets/images
  author: Yours truly <yours.truly@example.com>
  noodle:
    api-key: eC0GFio3Tz==