Schematize the Config

[michaeltlombardi]

As a platen site maintainer, I want to have validation and documentation for configuration settings while I author them and to be able to automatically test that my configurations are valid in cohesive way.

Schematizing the hugo configuration would allow users who are authoring their configurations in JSON or YAML¹ to get author-time validation, completion, and documentation for the basic configurable settings. As a basic level, this would entail:

1. Working on a schema for hugo itself. Luckily, while goghugoio/hugo#9725 is not yet implemented, @Emily added one to schemastore, which we can either use directly or base our own implementation on. I'm inclined primarily to support the public schema. One thing it currently lacks is a definition for the [params key]².

2. Schematizing the parameters for hugo-book, which this theme is based on. This could be contributed back upstream, but I'm not sure the maintainer has an interest in doing so. Ideally, the parameters for hugo-book would be namespaced under book, which would allow us to define a schema that would be compatible with hugo's configuration directory model. Right now, because those values are in the top-level, we need to do one of the following:

   1. Add the values applicable in ² to the upstream schema for hugo, define a separate schema for hugo-book's params, and define additional schemas for Platen-specific params.
   2. Merge the values applicable in ² with hugo-book's params as a custom schema, possibly including the Platen-specific params.

   We should investigate the possibility of injecting platen-scoped parameters to the values for hugo-book's params, so that:

   # config/params.platen.yaml
   Logo: /images/title.svg

   Would map in the site params somehow to .Site.Params.BookLogo without requiring the user to set that value or patching hugo-book itself.

3. Ensure any and all configuration files for Platen are schematized. At this time, the base theme doesn't have any configurable settings. However, toroidal does define some, it also places them in under a parent Toroidal key, like:

   #config.yaml
   params:
     Toroidal:
       WebringName: 'FooBar'

   Which means we can safely schematize those values for their own partial files in the configuration directory. Similarly, any and all configuration options for Platen itself should be namespaced for easier schematization and management.

An added bonus for this schematization is that with the Front Matter extension for VS Code, users will be able to use the data files view to configure their site, providing them with a nice UI that will also validate their configuration automatically. For us to fully leverage this, we would need to wait for estruyf/vscode-front-matter#407 or implement the workarounds described in #14 which will also benefit from that feature.

Aside from the Front Matter utilities, we could also implement a basic test kit that validates a site's configurations and iterate on that feature in the future, perhaps doing things like mapping overrides and noting when values in config files conflict, even though each file is valid.

This model should also support continued extensibility for Platen modules, making it easier for us to default to a more delightful UX.

Footnotes

1. The default in the template is YAML, because most of our users are unlikely to be familiar with TOML and YAML is "just" key-value pairs. We should also make sure we support JSON and TOML as best we can, though I don't think it's high priority for our users. There is a toml-schema option, and it might be possible to use JSON schemas against TOML files. ↩

2. The params key in the site configuration can contain values used by hugo's OpenGraph and Twitter card integrations to set site-wide defaults that can be overwritten on a per-page basis. ↩ ↩² ↩³