Request: handle empty config items for plugins

[RichardForshaw]

Explanation:

I am writing a plugin which generates additional content to documents. However some of this content is very simple and the only config item that is needed is to declare that it is present. But for others (of the same common type), some config will be needed. Think: buttons which only differ by appearance.

Current situation:

My plugin config has defaults that can either be inherited or customised, and looks like this:

plugins:
  myplugin:
    default_string: "A default"
    item1:
      present: true
      custom_string: "Customised"
    item2:
      present: true
    # User chooses not to include item3 in their pages

As you can see, because item2 uses the defaults, there is really no need for any config to be listed except to say that the user wants it included. However because the sub-items are all defined as SubConfig, they must have fields defined. I think this looks clunky and too verbose.

Current alternative

The alternative I use is to use the yaml {}:

plugins:
  myplugin:
    default_string: "A default"
    item1:
      custom_string: "Customised"
    item2: {}

This works but just looks a bit ugly.

Proposed solutions:

1. If a SubConfig is empty, instead of throwing an exception (that it is expecting a dict but got None), that it instead returns an empty dict. Then I can declare:

plugins:
  myplugin:
    default_string: "A default"
    item1:
      custom_string: "Customised"
    item2:
      # empty

I realise that this might also look a bit odd, so...

2. That a SubConfig can have two types, so it can be declared: e.g. item2 = config_options.SubConfig([CommonConfig, bool]) or similar. Then I can declare:

plugins:
  myplugin:
    default_string: "A default"
    item1:
      custom_string: "Customised"
    item2: true

This avoids the awkwardness of (1) and conveys the intent.

3. There is a way of using MKDocs and YAML that I am not aware of :)

[pawamoy]

I'll run some tests to see what is currently possible to do with MkDocs config API. In the meantime we recommend you use the "ugly" syntax 😄 Please ping me if I forget about this 🙂