Konfiguration
Die Qgoda-Konfiguration ist unkompliziert und hat sinnvolle Defaults. Eigentlich läuft Qgoda auch ohne jede Konfiguration. Die Software muss nur dann konfiguriert werden, wenn das Default-Verhalten angepasst werden soll.
Konfigurationsdateien
Qgoda has two optional configuration files, _qgoda.yaml and
_localqgoda.yaml. If you prefer, you can also use the file extension
.yml or .json, if you write the configuration in JSON format.
Qgodas verschiedene Konfigurationsebene
The configuration found in _qgoda.yaml overrides the built-in defaults,
and the configuration found in _localqgoda.yaml overrides both
_qgoda.yaml and the the built-in defaults.
Genauer gesagt, jede Konfigurationsebene wird mit der vorhergehenden kombiniert und überschreibt lediglich die Teile, die sich unterscheiden.
Die tatsächlich gültige Konfiguration kann man jederzeit mit dem Kommando qgoda config ermitteln, das die resultierende Konfiguration auf die Konsole ausgibt.
Weshalb _localconfig.yaml?
Qgoda funktioniert, wie die mieisten statischen Site-Generatoren, sehr gut mit git, und es kann sinnvoll sein, die Quelltexte der Site in einem öffentlich zugänglichen Git-Repository zur Verfügung zu stellen.
Aber was, wenn API-Schlüssel, Passwörter, private Informationen, lokale Rechnernamen oder Debug-Einstellungen in die Konfiguration eingefügt werden müssen. In all diesen Fällen kann man _localconfig.yaml verwenden, und die Datei dann nicht in das öffentliche Git-Repository einchekcne, sondern nur lokal verwenden.
Konfigurations-Variablen aus Templates ansprechen
Die vollständige Konfiguration der Site is über die Template-Variable config abrufbar:
<html>
<head>
<title>[% config.title | html %]
</head>
<body>
<h1>[% config.title | html %]</h1>
<div>[% asset.content %]</div>
</body>
</html>
So würde zum Beispiel die Konfigurations-Variable title aus einem Template angesprochen.
JSON-Schema
Um ungültige Konfigurationen zu verhindern, werden alle Einstellugen gegen ein JSON-Schema validiert. Das Schema kann auch mit dem Kommando qgoda schema angezeigt werden. Mit qgoda schema —help erhält man Auskunft über verschiedene Ausgabeformate des Schemas.
Während das Schreiben eines Schemas nicht wirklich trivial ist, kann es relative einfach gelesen werden.
Implementierung
Das Lesen der Konfiguration und die Validierung gegen das Schema erfolgt in JavaScript mit Ajv, einem mächtigen und schnellen Validator. Das Qgoda-Konfigurations-Schema ist kompatibel mit Version 0.7 der Spezifikation von JSON Schema.
Default-Werte
Die Defaults für alle Konfigurations-Optionen sind Teil des Schemas.
Automatische Typ-Konvertierung
JSON Schema ist streng typisiert. Wird für eine bestimmte Konfigurationsvariable eine Liste erwartet, wäre es normalerweise ein Fehler, einen String anzugeben. Qgoda verwendet jedoch automatische Typ-Konvertierung (engl. Type Coercion) und wandelt deshalb einen Einzelwert automatisch in eine Liste mit einem Element um.
Genauso erfordert eine boolsche Option normalerweise entweder true oder false. Mit automatischer Typ-Konvertierung kann man aber auch 0, einen leeren String oder null als Alias für false verwenden, und fast alles andere wird als true interpretiert. Eine vollständige Übersicht findet sich unter https://github.com/ajv-validator/ajv/blob/master/COERCION.md.
Programm-Pfade
It is very often necessary to configure a path to a program in _qgoda.yaml
for example in helpers or po.xgettext or others. This is a special
case where type coercion helps you to simplify the
configuration.
Ohne Argumente
Falls das Programm keine Argumente benötigt, kann es als einzelner String übergeben werden, zum Beispiel:
helpers:
assets: webpack
Mit Argumenten
Soll das Programm mit Argumenten aufgerufen werden, muss ein Array verwendet werden:
helpers:
assets:
- webpack
- --progress
- --colors
- --watch
Oder auch mit dieser alternativen Syntax für Arrays:
helpers:
assets: ['webpack', '--progress', '--colors', '--watch']
Eigene Konfigurations-Variablen zufügen
Your own configuration variables have to start either with site or private.
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 paths.home
because the slot
or namespace paths is already taken by Qgoda.
Diese Konfiguration dagegen wäre valide:
site:
paths:
images: _assets/images
author: Yours truly <yours.truly@example.com>
noodle:
api-key: eC0GFio3Tz==