JSON schema for Hugo

[EmilyGraceSeville7cf]

I've created a JSON schema for HUGO to add several hints in config.json/config.yml files. It covers most properties (but some of them have no descriptions due to documentation problems). I think it's better to place schema in this repo because HUGO maintainers better know HUGO and how it must work.

Please consider this PR the for the source code. I need help with the following things:

• properties without descriptions: write descriptions for them
• grammar in descriptions (please suggest better descriptions at your glance)

The descriptions have to be very short but descriptive.

[jmooring]

@EmilySeville7cfg

It looks like you have put a lot of effort into this, and conceptually it is a nice idea, but I'm not convinced that the value it provides is worth the effort to create and maintain.

1. Most sites that I have seen use TOML for configuration and YAML for front matter. If I had to guess, I would say YAML and JSON site configurations collectively represent 5-10% of all projects, at most.
2. The minimal site configuration for a single language, single output-format site is 3 lines, excluding menu entries and custom parameters. This is possible due to sane defaults, and we spend an agonizing amount of time making sure they are mostly right.
3. Or to look at it a different way, the best site configuration is the one that has the fewest entries possible to achieve the desired functionality. With that in mind, making it easy to add configuration values without a contextual understanding of the ramifications may cause more problems than it solves. I have seen this repeatedly in my efforts to support site authors.
4. Generally speaking, with the exception of menu entries and custom parameters, there really isn't much need to edit the site configuration over the project's lifetime. It's something you mostly do at the beginning of a project, with minor adjustments over time to add or modify functionality.

Again, I think it is a nice idea, but I have no interest in authoring, maintaining, or supporting it. If we were to prioritize this against all of the documented issues (bugs and enhancements), I think this effort would be in the bottom 5%.

I know that isn't what you want to hear, particularly after the apparent efforts you have made thus far.

[EmilyGraceSeville7cf]

I can maintain it myself via PRs. 😄 All bugs/enhancements for this schema can be assigned to me.

[michaeltlombardi]

I'm certainly interested in a schema for the configuration file as I find YAML configs easier to author and maintain, especially when they are accompanied by a schema, which many editors can take advantage of.

Configuring Hugo right now requires me to keep the docs open and refer back and forth, double checking everything. It's very easy to make a mistake and get a broken config because there's no author-time validation.

[skrysmanski]

Just quick note: With the rename from config.yaml to hugo.yaml vscode now pulls a (partially broken) JSON schema out of its head (which it also applies to yaml files).

[skrysmanski]

See also #10984.

[akbyrd]

@jmooring

Most sites that I have seen use TOML for configuration and YAML for front matter. If I had to guess, I would say YAML and JSON site configurations collectively represent 5-10% of all projects, at most.

Old comment at this point, but I figured it'd be worth pointing out that the json schema applies to all of hugo.toml. hugo.yaml, and hugo.json. Despite the name, json schemas can be used to validate multiple languages. https://github.com/SchemaStore/schemastore/blob/709e49c18e4f8679d58cd7c05404eb1391f7fa92/src/api/json/catalog.json#L5091

More broadly, as someone learning hugo, the validation is very helpful. Enough so that I'm actually fixing up some of the issues with the current schema as I encounter them. It can be a very effective way to discover options and get to the documentation quickly (the descriptions contain hyperlinks).

Having it maintained in the hugo repo opens the door for automating it. Assuming go has decent reflection, in theory the schema could be auto generated. It would be great to have a complete, correct, versioned schema to support the learning curve and provide a fast way to get to the documentation.