diff --git a/docs/img/color_mode_toggle_menu.png b/docs/img/color_mode_toggle_menu.png new file mode 100644 index 00000000..684c3d63 Binary files /dev/null and b/docs/img/color_mode_toggle_menu.png differ diff --git a/docs/img/mkdocs.png b/docs/img/mkdocs.png deleted file mode 100644 index b9011a29..00000000 Binary files a/docs/img/mkdocs.png and /dev/null differ diff --git a/docs/img/mkdocs_theme_dark_mode.png b/docs/img/mkdocs_theme_dark_mode.png new file mode 100644 index 00000000..f69b999e Binary files /dev/null and b/docs/img/mkdocs_theme_dark_mode.png differ diff --git a/docs/img/mkdocs_theme_light_mode.png b/docs/img/mkdocs_theme_light_mode.png new file mode 100644 index 00000000..91a9705f Binary files /dev/null and b/docs/img/mkdocs_theme_light_mode.png differ diff --git a/docs/user-guide/choosing-your-theme.md b/docs/user-guide/choosing-your-theme.md index 25026974..92d0eb65 100644 --- a/docs/user-guide/choosing-your-theme.md +++ b/docs/user-guide/choosing-your-theme.md @@ -21,17 +21,45 @@ theme: The default theme, which was built as a custom [Bootstrap] theme, supports almost every feature of MkDocs. -![mkdocs](../img/mkdocs.png) + In addition to the default [theme configuration options][theme], the `mkdocs` theme supports the following options: +* **`color_mode`**: Set the default color mode for the theme to one of `light`, + `dark`, or `auto`. The `auto` mode will switch to `light` or `dark` based on + the system configuration of the user's device. Default: `light`. + +* **`user_color_mode_toggle`**: Enable a toggle menu in the navigation bar + which allows users to select their preferred `color_mode` (light, dark, auto) + from within the browser and save their preference for future page loads. The + default selection of the toggle menu on first page load is the value set to + `color_mode`. Default: `false`. + + ![color mode toggle menu](../img/color_mode_toggle_menu.png) + +* **`nav_style`**: Adjust the visual style of the top navigation bar. Set to + one of `primary`, `dark` or `light`. Default: `primary`. This option is + independent of the `color_mode` option and must be defined separately. + * **`highlightjs`**: Enables highlighting of source code in code blocks using the [highlight.js] JavaScript library. Default: `True`. -* **`hljs_style`**: The highlight.js library provides 79 different [styles] +* **`hljs_style`**: The highlight.js library provides many different [styles] (color variations) for highlighting source code in code blocks. Set this to - the name of the desired style. Default: `github`. + the name of the desired style when in `light` mode. Default: `github`. + +* **`hljs_style_dark`**: Set this to the name of the desired highlight.js + style when in `dark` mode. Default: `github_dark`. * **`hljs_languages`**: By default, highlight.js only supports 23 common languages. List additional languages here to include support for them. @@ -91,16 +119,6 @@ supports the following options: * **`navigation_depth`**: The maximum depth of the navigation tree in the sidebar. Default: `2`. -* **`nav_style`**: This adjusts the visual style for the top navigation bar; by - default, this is set to `primary` (the default), but it can also be set to - `dark` or `light`. - - ```yaml - theme: - name: mkdocs - nav_style: dark - ``` - * **`locale`**{ #mkdocs-locale }: The locale (language/location) used to build the theme. If your locale is not yet supported, it will fall back to the default. diff --git a/mkdocs.yml b/mkdocs.yml index 56b65d87..7246e148 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,6 +8,8 @@ edit_uri: blob/master/docs/ theme: name: mkdocs + color_mode: auto + user_color_mode_toggle: true locale: en analytics: {gtag: 'G-274394082'} highlightjs: true diff --git a/mkdocs/tests/config/config_tests.py b/mkdocs/tests/config/config_tests.py index 54693188..6299d37f 100644 --- a/mkdocs/tests/config/config_tests.py +++ b/mkdocs/tests/config/config_tests.py @@ -105,6 +105,8 @@ class ConfigTests(unittest.TestCase): 'static_templates': ['404.html', 'sitemap.xml'], 'vars': { 'name': 'mkdocs', + 'color_mode': 'light', + 'user_color_mode_toggle': False, 'locale': parse_locale('en'), 'include_search_page': False, 'search_index_only': False, @@ -112,6 +114,7 @@ class ConfigTests(unittest.TestCase): 'highlightjs': True, 'hljs_style': 'github', 'hljs_languages': [], + 'hljs_style_dark': 'github-dark', 'navigation_depth': 2, 'nav_style': 'primary', 'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}, @@ -190,6 +193,8 @@ class ConfigTests(unittest.TestCase): 'static_templates': ['404.html', 'sitemap.xml', 'foo.html'], 'vars': { 'name': 'mkdocs', + 'color_mode': 'light', + 'user_color_mode_toggle': False, 'locale': parse_locale('fr'), 'show_sidebar': False, 'some_var': 'bar', @@ -199,6 +204,7 @@ class ConfigTests(unittest.TestCase): 'highlightjs': True, 'hljs_style': 'github', 'hljs_languages': [], + 'hljs_style_dark': 'github-dark', 'navigation_depth': 2, 'nav_style': 'primary', 'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}, diff --git a/mkdocs/tests/theme_tests.py b/mkdocs/tests/theme_tests.py index 2b1aea90..f9989fb3 100644 --- a/mkdocs/tests/theme_tests.py +++ b/mkdocs/tests/theme_tests.py @@ -25,12 +25,15 @@ class ThemeTests(unittest.TestCase): dict(theme), { 'name': 'mkdocs', + 'color_mode': 'light', + 'user_color_mode_toggle': False, 'locale': parse_locale('en'), 'include_search_page': False, 'search_index_only': False, 'analytics': {'gtag': None}, 'highlightjs': True, 'hljs_style': 'github', + 'hljs_style_dark': 'github-dark', 'hljs_languages': [], 'navigation_depth': 2, 'nav_style': 'primary', diff --git a/mkdocs/themes/mkdocs/base.html b/mkdocs/themes/mkdocs/base.html index 5ce5fd03..1a9b1cb3 100644 --- a/mkdocs/themes/mkdocs/base.html +++ b/mkdocs/themes/mkdocs/base.html @@ -1,5 +1,5 @@ - + {%- block site_meta %} @@ -24,7 +24,8 @@ {%- if config.theme.highlightjs %} - + + {%- endif %} {%- for path in config.extra_css %} @@ -108,7 +109,7 @@ {%- endif %} {%- endblock %} -