Add theme specific configuration. #1164
Comments
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 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 If we decide to only support type A variables, then I suppose themes can continue to use |
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 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. |
I suspect option 3 is needed. My feeling is that 1 or 2 on their own wont feel complete. |
In my original proposal I suggested the following format for the config in 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 The theme itself would not be able to set the We could even include a setting |
FYI to those interested. The work on this is happening here: 1.0.dev...waylan:themes. |
Currently, in addition to building (Markdown) pages via
main.html
, we have hardcoded provisions for theme templates to build404.html
,search.html
, andsitemap.xml
. However, there is no way for a theme to provide any additional pages (sitemap.html
or Sphinx'sgenindex.html
).We do have the
extra_templates
config setting, but that specifically assumes the template files are in thedocs_dir
, not at a path in the Jinja environment (they go throughmkdocs.commands.build.build_extra_templates()
rather thanmkdocs.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:
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 throughbuild_template
. As prior art, Sphinx themes provide for aconfig.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.We could allow nested config settings in
mkdocs.yml
. Following existing conventions, perhaps something like: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 toTrue
but the user can set toFalse
).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. Andextra
does not provide a way for a theme to pass more templates throughbuild_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.The text was updated successfully, but these errors were encountered: