Features
-
+
Great themes available
@@ -40,7 +40,7 @@ configuration file. Start by reading the [introductory tutorial], then check the
-
+
@@ -190,7 +225,7 @@
{%- block scripts %}
-
+
Easy to customize
diff --git a/docs/user-guide/choosing-your-theme.md b/docs/user-guide/choosing-your-theme.md index 2502697489..92d0eb653e 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. - +
+
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`.
+
+ 
+
+* **`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 56b65d87a9..7246e14865 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/build_tests.py b/mkdocs/tests/build_tests.py
index 2ad9353200..d2dd3ca04e 100644
--- a/mkdocs/tests/build_tests.py
+++ b/mkdocs/tests/build_tests.py
@@ -550,7 +550,7 @@ def test_copy_theme_files(self, site_dir, docs_dir):
self.assertPathIsDir(site_dir, 'js')
self.assertPathIsDir(site_dir, 'css')
self.assertPathIsDir(site_dir, 'img')
- self.assertPathIsDir(site_dir, 'fonts')
+ self.assertPathIsDir(site_dir, 'webfonts')
self.assertPathNotExists(site_dir, '__init__.py')
self.assertPathNotExists(site_dir, '__init__.pyc')
self.assertPathNotExists(site_dir, 'base.html')
diff --git a/mkdocs/tests/config/config_tests.py b/mkdocs/tests/config/config_tests.py
index 54693188c1..6299d37f39 100644
--- a/mkdocs/tests/config/config_tests.py
+++ b/mkdocs/tests/config/config_tests.py
@@ -105,6 +105,8 @@ def test_theme(self, mytheme, custom):
'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 @@ def test_theme(self, mytheme, custom):
'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 @@ def test_theme(self, mytheme, custom):
'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 @@ def test_theme(self, mytheme, custom):
'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 2b1aea9008..f9989fb3f4 100644
--- a/mkdocs/tests/theme_tests.py
+++ b/mkdocs/tests/theme_tests.py
@@ -25,12 +25,15 @@ def test_simple_theme(self):
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 2b077bd016..1a9b1cb33a 100644
--- a/mkdocs/themes/mkdocs/base.html
+++ b/mkdocs/themes/mkdocs/base.html
@@ -1,5 +1,5 @@
-
+
{%- block site_meta %}
@@ -18,10 +18,14 @@
{%- block styles %}
-
+
+
+
+
{%- if config.theme.highlightjs %}
-
+
+
{%- endif %}
{%- for path in config.extra_css %}
@@ -74,7 +78,7 @@
{%- if nav|length>1 or (page and (page.next_page or page.previous_page)) or config.repo_url %}
-
+
+
+ 
+
+
+
+ 
+
+
+