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/ajv-validator/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']
All other possible configuration variables are reserved by Qgoda, and those
support have a
fixed syntax and you must adhere to it. This is a meant as a protection against
typos. As a consquence, you cannot add a configuration variable
slot or namespace
paths is already taken by Qgoda.
This, however, would be safe:
site: paths: images: _assets/images author: Yours truly <email@example.com> noodle: api-key: eC0GFio3Tz==