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 🙂

[kchr]

Personally I would prefer the first solution of the two proposed.

As an example, this is supported by the YAML files that GitHub use for their Workflow definitions:

# Simple workflow for building static content from source
name: Build and deploy documentation on Pages

on:
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

  # Allows workflow to be called from another workflow
  workflow_call:

Here, workflow_dispatch and workflow_call are declared as keys for the on map but are empty, as we do not want to set any custom values for them. GitHub will accept that and consider both on.workflow_dispatch and on.workflow_call to be present.