Add theme specific configuration.

[waylan]

Currently, in addition to building (Markdown) pages via main.html, we have hardcoded provisions for theme templates to build 404.html, search.html, and sitemap.xml. However, there is no way for a theme to provide any additional pages (sitemap.html or Sphinx's genindex.html).

We do have the extra_templates config setting, but that specifically assumes the template files are in the docs_dir, not at a path in the Jinja environment (they go through mkdocs.commands.build.build_extra_templates() rather than mkdocs.commands.build.build_template()).

In the work on Plugins (#206), a plugin can alter the config and add an additional directory to the Jinja Environment. That same plugin can also add a hook which explicitly calls mkdocs.commands.build.build_template() with a template in its template dir (that's how I implemented search as a plugin). However, themes have no way to alter the config.

To allow something like this, we need some way to allow configuration for themes. I see a few possibilities:

1. The theme could include a config file which defines specific variables. For example an extra_templates variable could include a list of additional templates to pass through build_template. As prior art, Sphinx themes provide for a config.ini file in their root dir. We might want to use a .yml file instead to match our config file format. Or we could use Python in the required __init__.py file.

2. We could allow nested config settings in mkdocs.yml. Following existing conventions, perhaps something like:

   theme:
       themename:
           - extra_templates: [sitemap.html]
           - include_sidebar: false

3. A combination of the two. The theme author could define some defaults and the user could override them. This would also make a great way for themes to define optional behavior (include_sidebar which defaults to True but the user can set to False).

Yes, we have the extra config setting. While that is already used by third party themes to enable/disable theme features, the theme has to provide for the setting not being defined at all. And extra does not provide a way for a theme to pass more templates through build_template.

If we just want to allow a theme to pass more pages through build_template, then option 1 makes the most sense to me. But personally, I would prefer option 3. Option 2 would work, but the user would need to explicitly set each setting before it would be defined at all.

[waylan]

In case it isn't clear, I'm proposing two types of theme specific config setting variables:

A. Variables predefined by MkDocs. This would include the extra_templates setting in the examples above. MkDocs knows about these settings and has code included to do specific things with them.

B. Variables defined by the theme author. These would essentially be a more formal way for theme authors to add their own configs (instead of using extra).

If we decide to only support type A variables, then I suppose themes can continue to use extra. But I think extra should be reserved for user specific stuff, whereas theme specific things make more sense if they are specifically associated with the theme.

[waylan]

Another potential use-case for Type A variables would be to identify which version of MkDocs a theme is expected to work with. For example, some changes in 0.16 issue warnings, but things will break in the next release if the templates are not updated. A setting indicating that the theme only works with mkdocs<=0.16 could then raise a validation error if the user has mkdocs>0.16 installed.

While themes already are Python packages (which provide some support for this), MkDocs does not list the third party theme as a dependency. So if the user updated MkDocs, but not the theme, things could break in unfriendly ways. However, with such a feature, the user would instead get a helpful error message telling them to check to see if their theme has an update, rather than thinking that MkDocs is broken.

[d0ugal]

I suspect option 3 is needed. My feeling is that 1 or 2 on their own wont feel complete.

[waylan]

In my original proposal I suggested the following format for the config in mkdocs.yaml (where"themename" is the name of the theme:

theme:
    themename:
        - extra_templates: [sitemap.html]
        - include_sidebar: false

There would only ever be a single theme defined, so that format (shared by markdown extensions and the proposed plugin API, each of which could have multiple items listed) does not make much sense here.

It occurs to me that we could instead do this:

theme:
    name: 'themename'
    custom_dir: 'path/to/user/overrides'
    extra_templates: [sitemap.html]
    include_sidebar: false

Then the current interaction between the theme and theme_dir settings would be moved to the nested name and custom_dir (leave name blank to have an entire theme in the custom_dir, or define both to have user defined templates override/replace the theme provided templates.)

The theme itself would not be able to set the custom_dir setting (any value would be ignored). That setting is only for the end user. Themes define their location via the existing entry_point assigned to the name.

We could even include a setting extends (or inherits_from) which would allow one theme to inherit base templates from another theme (Sphinx does this with a lot of their builtin themes). While this could be accomplished with either format, it feels more natural with this one (to me).

[waylan]

FYI to those interested. The work on this is happening here: 1.0.dev...waylan:themes.