From 4b8626c16680efde5acb7962d9fce3c190903b4f Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Thu, 19 Oct 2017 10:48:57 -0400 Subject: [PATCH] Improved theme config docs. --- docs/about/release-notes.md | 14 +++++++++----- docs/user-guide/custom-themes.md | 4 ++-- docs/user-guide/styling-your-docs.md | 11 +++++++++++ 3 files changed, 22 insertions(+), 7 deletions(-) diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 3d6aa7ab..790f696f 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -46,12 +46,16 @@ Support had been added to provide theme specific customizations. Theme authors can define default options as documented in [Theme Configuration]. A theme can now inherit from another theme, define various static templates to be rendered, and define arbitrary default variables to control behavior in the templates. +The theme configuration is defined in a configuruation file named +`mkdocs_theme.yml` which should be placed at the root of your template files. A +warning will be raised if no configuration file is found and an error will be +raised in a future release. -Users can override those defaults under the [theme] configuration option, which -now accepts nested options. One such nested option is the [custom_dir] option, -which replaces the now deprecated `theme_dir` option. If users had previously -set the `theme_dir` option, a warning will be issued, with an error expected in -a future release. +Users can override those defaults under the [theme] configuration option of +their `mkdocs.yml` configuration file, which now accepts nested options. One +such nested option is the [custom_dir] option, which replaces the now deprecated +`theme_dir` option. If users had previously set the `theme_dir` option, a +warning will be issued, with an error expected in a future release. If a configuration previously defined a `theme_dir` like this: diff --git a/docs/user-guide/custom-themes.md b/docs/user-guide/custom-themes.md index cea08b0c..266ba2ea 100644 --- a/docs/user-guide/custom-themes.md +++ b/docs/user-guide/custom-themes.md @@ -468,7 +468,7 @@ directory is a package. ### Theme Configuration A packaged theme is required to include a configuration file named -`mkdocs.theme.yml` which is placed in the root of your template files. The file +`mkdocs_theme.yml` which is placed in the root of your template files. The file should contain default configuration options for the theme. However, if the theme offers no configuration options, the file is still required and can be left blank. @@ -476,7 +476,7 @@ left blank. The theme author is free to define any arbitrary options deemed necessary and those options will be made available in the templates to control behavior. For example, a theme might want to make a sidebar optional and include the -following in the `mkdocs-theme.yml` file: +following in the `mkdocs_theme.yml` file: ```yaml show_sidebar: true diff --git a/docs/user-guide/styling-your-docs.md b/docs/user-guide/styling-your-docs.md index 0d9314a0..4837e8f6 100644 --- a/docs/user-guide/styling-your-docs.md +++ b/docs/user-guide/styling-your-docs.md @@ -25,10 +25,18 @@ the [Customizing a Theme][customize] section below. ### mkdocs +The default theme, which was built as a custom [Bootstrap] theme, supports most +every feature of MkDocs. It only supports the default +[theme configuration options]. + ![mkdocs](/img/mkdocs.png) ### readthedocs +A clone of the default theme used by the [Read the Docs] service. This theme +only supports features in its parent theme and does not support any MkDocs +[theme configuration options] in addition to the defaults. + ![ReadTheDocs](http://docs.readthedocs.io/en/latest/_images/screen_mobile.png) ### Third Party Themes @@ -252,6 +260,9 @@ any additional CSS files included in the `custom_dir`. [browse source]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs [built-in themes]: #built-in-themes +[Bootstrap]: http://getbootstrap.com/ +[theme configuration options]: configuration.md#theme +[Read the Docs]: https://readthedocs.org/ [community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes [custom theme]: ./custom-themes.md [customize]: #customizing-a-theme