Merge pull request #3493 from waylan/2248

Update mkdocs theme to bootstrap 5.3 and add support for dark mode.

.jshintignore

@@ -1,6 +1,6 @@
 mkdocs/themes/**/js/jquery-**.min.js
 mkdocs/themes/mkdocs/js/highlight.pack.js
-mkdocs/themes/mkdocs/js/bootstrap.min.js
+mkdocs/themes/mkdocs/js/bootstrap.bundle.min.js
 mkdocs/themes/mkdocs/js/modernizr-**.min.js
 mkdocs/themes/readthedocs/js/theme.js
 mkdocs/themes/readthedocs/js/html5shiv.min.js

docs/css/extra.css

@@ -21,14 +21,14 @@ div.admonition.block>.admonition-title {
 }
 
 .admonition.new, details.new {
-    color: #15654a;
-    background-color: #edfff9;
-    border-color: #bcf1e8;
+    color: var(--bs-success-text-emphasis);
+    background-color: var(--bs-success-bg-subtle);
+    border-color: var(--bs-success-border-subtle);
 }
 .admonition.example, details.example {
-    color: #353579;
-    background-color: #f0f1ff;
-    border-color: #d8dcf0;
+    color: var(--bs-info-text-emphasis);
+    background-color: var(--bs-info-bg-subtle);
+    border-color: var(--bs-info-border-subtle);
 }
 
 /* Definition List styles */
@@ -45,16 +45,6 @@ dd {
 
 /* Homepage */
 
-body.homepage div.jumbotron {
-    margin-top: 1.5rem;
-    padding-top: 1rem;
-    padding-bottom: 0;
-}
-
-body.homepage div.jumbotron div.card {
-    margin-bottom: 2rem;
-}
-
 body.homepage>div.container>div.row>div.col-md-3 {
     display: none;
 }
@@ -69,7 +59,7 @@ body.homepage>div.container>div.row>div.col-md-9 {
 
 .doc-object {
     padding-left: 10px;
-    border-left: 4px solid rgba(230, 230, 230);
+    border-left: 4px solid var(--bs-light-border-subtle);
 }
 
 .doc-contents .field-body p:first-of-type {

docs/index.md

@@ -18,12 +18,12 @@ configuration file. Start by reading the [introductory tutorial], then check the
 <a href="user-guide/" class="btn btn-primary" role="button">User Guide</a>
 </div>
 
-<div class="jumbotron">
+<div class="pt-2 pb-4 px-4 my-4 bg-body-tertiary rounded-3">
 <h2 class="display-4 text-center">Features</h2>
 
 <div class="row">
   <div class="col-sm-6">
-    <div class="card">
+    <div class="card mb-4">
       <div class="card-body">
         <h3 class="card-title">Great themes available</h3>
         <p class="card-text">
@@ -40,7 +40,7 @@ configuration file. Start by reading the [introductory tutorial], then check the
     </div>
   </div>
   <div class="col-sm-6">
-    <div class="card">
+    <div class="card mb-4">
       <div class="card-body">
         <h3 class="card-title">Easy to customize</h3>
         <p class="card-text">

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)
+<div id="mkdocs-theme-images" class="carousel slide carousel-fade" data-bs-ride="carousel">
+  <div class="carousel-inner">
+    <div class="carousel-item active">
+      <img src="../../img/mkdocs_theme_light_mode.png" class="d-block w-100" alt="MkDocs theme in light mode">
+    </div>
+    <div class="carousel-item">
+      <img src="../../img/mkdocs_theme_dark_mode.png" class="d-block w-100" alt="MkDocs theme in dark mode">
+    </div>
+  </div>
+</div>
 
 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.

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

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')

mkdocs/tests/config/config_tests.py

@@ -105,13 +105,16 @@ 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,
                     'analytics': {'gtag': None},
                     '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},

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',

mkdocs/themes/mkdocs/base.html

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="{{ config.theme.locale|default('en') }}">
+<html lang="{{ config.theme.locale|default('en') }}" data-bs-theme="{{ config.theme.color_mode }}">
     <head>
       {%- block site_meta %}
         <meta charset="utf-8">
@@ -18,10 +18,14 @@
 
       {%- block styles %}
         <link href="{{ 'css/bootstrap.min.css'|url }}" rel="stylesheet">
-        <link href="{{ 'css/font-awesome.min.css'|url }}" rel="stylesheet">
+        <link href="{{ 'css/fontawesome.min.css'|url }}" rel="stylesheet">
+        <link href="{{ 'css/brands.min.css'|url }}" rel="stylesheet">
+        <link href="{{ 'css/solid.min.css'|url }}" rel="stylesheet">
+        <link href="{{ 'css/v4-font-face.min.css'|url }}" rel="stylesheet">
         <link href="{{ 'css/base.css'|url }}" rel="stylesheet">
         {%- if config.theme.highlightjs %}
-        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/{{ config.theme.hljs_style }}.min.css">
+        <link id="hljs-light" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/{{ config.theme.hljs_style }}.min.css" {% if config.theme.color_mode != "light" %}disabled{% endif %}>
+        <link id="hljs-dark" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/{{ config.theme.hljs_style_dark }}.min.css" {% if config.theme.color_mode != "dark" %}disabled{% endif %}>
         {%- endif %}
         {%- for path in config.extra_css %}
         <link href="{{ path|url }}" rel="stylesheet">
@@ -74,7 +78,7 @@
 
                 {%- if nav|length>1 or (page and (page.next_page or page.previous_page)) or config.repo_url %}
                 <!-- Expander button -->
-                <button type="button" class="navbar-toggler" data-toggle="collapse" data-target="#navbar-collapse">
+                <button type="button" class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#navbar-collapse" aria-controls="navbar-collapse" aria-expanded="false" aria-label="Toggle navigation">
                     <span class="navbar-toggler-icon"></span>
                 </button>
                 {%- endif %}
@@ -87,29 +91,29 @@
                         <ul class="nav navbar-nav">
                         {%- for nav_item in nav %}
                         {%- if nav_item.children %}
-                            <li class="dropdown{% if nav_item.active %} active{% endif %}">
-                                <a href="#" class="nav-link dropdown-toggle" data-toggle="dropdown">{{ nav_item.title }} <b class="caret"></b></a>
+                            <li class="nav-item dropdown">
+                                <a href="#" class="nav-link dropdown-toggle{% if nav_item.active %} active" aria-current="page{% endif %}" role="button" data-bs-toggle="dropdown"  aria-expanded="false">{{ nav_item.title }}</a>
                                 <ul class="dropdown-menu">
                                 {%- for nav_item in nav_item.children %}
                                     {% include "nav-sub.html" %}
                                 {%- endfor %}
                                 </ul>
                             </li>
                         {%- else %}
-                            <li class="navitem{% if nav_item.active %} active{% endif %}">
-                                <a href="{{ nav_item.url|url }}" class="nav-link">{{ nav_item.title }}</a>
+                            <li class="nav-item">
+                                <a href="{{ nav_item.url|url }}" class="nav-link{% if nav_item.active %} active" aria-current="page{% endif %}">{{ nav_item.title }}</a>
                             </li>
                         {%- endif %}
                         {%- endfor %}
                         </ul>
                     {%- endif %}
                   {%- endblock %}
 
-                    <ul class="nav navbar-nav ml-auto">
+                    <ul class="nav navbar-nav ms-md-auto">
                       {%- block search_button %}
                         {%- if 'search' in config.plugins %}
                         <li class="nav-item">
-                            <a href="#" class="nav-link" data-toggle="modal" data-target="#mkdocs_search_modal">
+                            <a href="#" class="nav-link" data-bs-toggle="modal" data-bs-target="#mkdocs_search_modal">
                                 <i class="fa fa-search"></i> {% trans %}Search{% endtrans %}
                             </a>
                         </li>
@@ -136,11 +140,11 @@
                             <li class="nav-item">
                                 <a href="{{ page.edit_url }}" class="nav-link">
                                     {%- if config.repo_name == 'GitHub' -%}
-                                        <i class="fa fa-github"></i> {% trans repo_name=config.repo_name %}Edit on {{ repo_name }}{% endtrans %}
+                                        <i class="fa-brands fa-github"></i> {% trans repo_name=config.repo_name %}Edit on {{ repo_name }}{% endtrans %}
                                     {%- elif config.repo_name == 'Bitbucket' -%}
-                                        <i class="fa fa-bitbucket"></i> {% trans repo_name=config.repo_name %}Edit on {{ repo_name }}{% endtrans %}
+                                        <i class="fa-brands fa-bitbucket"></i> {% trans repo_name=config.repo_name %}Edit on {{ repo_name }}{% endtrans %}
                                     {%- elif config.repo_name == 'GitLab' -%}
-                                        <i class="fa fa-gitlab"></i> {% trans repo_name=config.repo_name %}Edit on {{ repo_name }}{% endtrans %}
+                                        <i class="fa-brands fa-gitlab"></i> {% trans repo_name=config.repo_name %}Edit on {{ repo_name }}{% endtrans %}
                                     {%- elif config.repo_name -%}
                                         {% trans repo_name=config.repo_name%}Edit on {{ repo_name }}{% endtrans %}
                                     {% else %}
@@ -164,6 +168,37 @@
                             </li>
                         {%- endif %}
                       {%- endblock %}
+                      {%- if config.theme.user_color_mode_toggle %}
+                            <li class="nav-item dropdown">
+                              <button id="theme-menu" aria-expanded="false" data-bs-toggle="dropdown" data-bs-display="static" aria-label="Toggle theme" class="nav-link dropdown-toggle">
+                                <i class="fa-solid fa-circle-half-stroke fa-fw"></i>
+                                <span class="d-lg-none ms-2">Toggle theme</span>
+                              </button>
+                              <ul class="dropdown-menu dropdown-menu-end">
+                                <li>
+                                  <button class="dropdown-item d-flex align-items-center" data-bs-theme-value="light" aria-pressed="{% if config.theme.color_mode == 'light' %}true{% else %}false{% endif %}">
+                                    <i class="fa-solid fa-sun fa-fw"></i>
+                                    <span class="ms-2">Light</span>
+                                    <i class="fa-solid fa-check ms-auto{% if config.theme.color_mode != 'light' %} d-none{% endif %}"></i>
+                                  </button>
+                                </li>
+                                <li>
+                                  <button class="dropdown-item d-flex align-items-center" data-bs-theme-value="dark" aria-pressed="{% if config.theme.color_mode == 'dark' %}true{% else %}false{% endif %}">
+                                    <i class="fa-solid fa-moon fa-fw"></i>
+                                    <span class="ms-2">Dark</span>
+                                    <i class="fa-solid fa-check ms-auto{% if config.theme.color_mode != 'dark' %} d-none{% endif %}"></i>
+                                  </button>
+                                </li>
+                                <li>
+                                  <button class="dropdown-item d-flex align-items-center" data-bs-theme-value="auto" aria-pressed="{% if config.theme.color_mode == 'auto' %}true{% else %}false{% endif %}">
+                                    <i class="fa-solid fa-circle-half-stroke fa-fw"></i>
+                                    <span class="ms-2">Auto</span>
+                                    <i class="fa-solid fa-check ms-auto{% if config.theme.color_mode != 'auto' %} d-none{% endif %}"></i>
+                                  </button>
+                                </li>
+                              </ul>
+                            </li>
+                    {%- endif %}
                     </ul>
                 </div>
             </div>
@@ -190,7 +225,7 @@
 
       {%- block scripts %}
         <script src="{{ 'js/jquery-3.6.0.min.js'|url }}"></script>
-        <script src="{{ 'js/bootstrap.min.js'|url }}"></script>
+        <script src="{{ 'js/bootstrap.bundle.min.js'|url }}"></script>
         <script>
             var base_url = {{ base_url|tojson }},
                 shortcuts = {{ config.theme.shortcuts|tojson }};