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.
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.
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.
The entire configuration of the site is accessible in the template variable
<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
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.
The defaults for all configuration options are part of the schema.
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
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.
It is very often necessary to configure a path to a program in
for example in
po.xgettext or others. This is a special
case where type coercion helps you to simplify the
If the program does not take any arguments, you can pass it as a single string, for example:
helpers: assets: webpack
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']
You can add your own configuration variables to your heart's delight but
slots already in use by Qgoda. For example, you cannot add a
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
local which is guaranteed not to be used by Qgoda itself:
local: paths: images: _assets/images author: Yours truly <firstname.lastname@example.org> noodle: api-key: eC0GFio3Tz==