Update mkdocs theme to Bootstrap/Bootswatch 5.3.2

Javascript has been updated to Bootstrap version 5.3.2 and CSS has been updated to the the Bootswatch Cerulean theme version 5.3.2. Adding support for a dark mode to the mkdocs theme is now possible. All local colors (in base.css, extra.css, etc.) are now defined using Bootstrap variables so that any future color modes (such as dark mode) will be consistent. Admonition styles have also been fully fleshed out with all colors being Bootstrap colors (via variables) rather than our own custom colors. Note that while Bootstrap version 5 dropped a dependency on jQuery, the mkdocs theme is still making use of jQuery at this time. However, future changes could remove the need for this dependency. Co-authored-by: Oleh Prypin <[email protected]>
lakamson · Mar 16, 2024 · 351b879 · 351b879
1 parent 53ff03a
commit 351b879
Show file tree

Hide file tree

Showing 16 changed files with 126 additions and 99 deletions.
diff --git a/.jshintignore b/.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

diff --git a/docs/css/extra.css b/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 {

diff --git a/docs/index.md b/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">

diff --git a/mkdocs/themes/mkdocs/base.html b/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="light">
     <head>
       {%- block site_meta %}
         <meta charset="utf-8">
@@ -74,7 +74,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,17 +87,17 @@
                         <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 %}
@@ -109,7 +109,7 @@
                       {%- 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>
@@ -190,7 +190,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 }};

diff --git a/mkdocs/themes/mkdocs/css/base.css b/mkdocs/themes/mkdocs/css/base.css
@@ -13,7 +13,7 @@ body::before {
     height: 100%;
     top: 0;
     left: 0;
-    background-color: #f8f8f8;
+    background-color: var(--bs-body-bg);
     background: url(../img/grid.png) repeat-x;
     will-change: transform;
     z-index: -1;
@@ -38,32 +38,33 @@ body > .container {
     display: inline-block;
     padding: 4px;
     line-height: 1.428571429;
-    background-color: #fff;
-    border: 1px solid #ddd;
+    background-color: var(--bs-secondary-bg-subtle);
+    border: 1px solid var(--bs-secondary-border-subtle);
     border-radius: 4px;
     margin: 20px auto 30px auto;
 }
 
 h1 {
-    color: #444;
+    color: inherit;
     font-weight: 400;
     font-size: 42px;
 }
 
 h2, h3, h4, h5, h6 {
-    color: #444;
+    color: inherit;
     font-weight: 300;
 }
 
 hr {
     border-top: 1px solid #aaa;
+    opacity: 1;
 }
 
 pre, .rst-content tt {
     max-width: 100%;
-    background: #fff;
-    border: solid 1px #e1e4e5;
-    color: #333;
+    background-color: var(--bs-body-bg);
+    border: solid 1px var(--bs-border-color);
+    color: var(--bs-body-color);
     overflow-x: auto;
 }
 
@@ -73,16 +74,15 @@ code.code-large, .rst-content tt.code-large {
 
 code {
     padding: 2px 5px;
-    background: #fff;
-    border: solid 1px #e1e4e5;
-    color: #333;
+    background-color: rgba(var(--bs-body-bg-rgb), 0.75);
+    border: solid 1px var(--bs-border-color);
+    color: var(--bs-body-color);
     white-space: pre-wrap;
     word-wrap: break-word;
 }
 
 pre code {
     display: block;
-    background: transparent;
     border: none;
     white-space: pre;
     word-wrap: normal;
@@ -93,19 +93,19 @@ pre code {
 kbd {
     padding: 2px 4px;
     font-size: 90%;
-    color: #fff;
-    background-color: #333;
+    color: var(--bs-secondary-text-emphasis);
+    background-color: var(--bs-secondary-bg-subtle);
     border-radius: 3px;
     -webkit-box-shadow: inset 0 -1px 0 rgba(0,0,0,.25);
     box-shadow: inset 0 -1px 0 rgba(0,0,0,.25);
 }
 
 a code {
-    color: #2FA4E7;
+    color: inherit;
 }
 
 a:hover code, a:focus code {
-    color: #157AB5;
+    color: inherit;
 }
 
 footer {
@@ -201,6 +201,8 @@ footer {
     font-size: 14px;
     display: none;
     padding-left: .5em;
+    text-decoration: none;
+    vertical-align: middle;
 }
 
 h1:hover .headerlink, h2:hover .headerlink, h3:hover .headerlink, h4:hover .headerlink, h5:hover .headerlink, h6:hover .headerlink {
@@ -220,22 +222,69 @@ blockquote {
     text-align: left;
 }
 
-.admonition.note, details.note, .admonition.info, details.info {
-    color: #2e6b89;
-    background-color: #e2f0f7;
-    border-color: #bce8f1;
+.admonition.note, details.note {
+    color: var(--bs-primary-text-emphasis);
+    background-color: var(--bs-primary-bg-subtle);
+    border-color: var(--bs-primary-border-subtle);
+}
+
+.admonition.note h1, .admonition.note h2, .admonition.note h3,
+.admonition.note h4, .admonition.note h5, .admonition.note h6,
+details.note h1, details.note h2, details.note h3,
+details.note h4, details.note h5, details.note h6 {
+    color: var(--bs-primary-text-emphasis);
+}
+
+.admonition.info, details.info {
+    color: var(--bs-info-text-emphasis);
+    background-color: var(--bs-info-bg-subtle);
+    border-color: var(--bs-info-border-subtle);
+}
+
+.admonition.info h1, .admonition.info h2, .admonition.info h3,
+.admonition.info h4, .admonition.info h5, .admonition.info h6,
+details.info h1, details.info h2, details.info h3,
+details.info h4, details.info h5, details.info h6 {
+    color: var(--bs-info-text-emphasis);
 }
 
 .admonition.warning, details.warning {
-    color: #7a6032;
-    background-color: #fffae5;
-    border-color: #fbeed5;
+    color: var(--bs-warning-text-emphasis);
+    background-color: var(--bs-warning-bg-subtle);
+    border-color: var(--bs-warning-border-subtle);
+}
+
+.admonition.warning h1, .admonition.warning h2, .admonition.warning h3,
+.admonition.warning h4, .admonition.warning h5, .admonition.warning h6,
+details.warning h1, details.warning h2, details.warning h3,
+details.warning h4, details.warning h5, details.warning h6 {
+    color: var(--bs-warning-text-emphasis);
 }
 
 .admonition.danger, details.danger {
-    color: #7f3130;
-    background-color: #fde3e3;
-    border-color: #eed3d7;
+    color: var(--bs-danger-text-emphasis);
+    background-color: var(--bs-danger-bg-subtle);
+    border-color: var(--bs-danger-border-subtle);
+}
+
+.admonition.danger h1, .admonition.danger h2, .admonition.danger h3,
+.admonition.danger h4, .admonition.danger h5, .admonition.danger h6,
+details.danger h1, details.danger h2, details.danger h3,
+details.danger h4, details.danger h5, details.danger h6 {
+    color: var(--bs-danger-text-emphasis);
+}
+
+.admonition, details {
+    color: var(--bs-light-text-emphasis);
+    background-color: var(--bs-light-bg-subtle);
+    border-color: var(--bs-light-border-subtle);
+}
+
+.admonition h1, .admonition h2, .admonition h3,
+.admonition h4, .admonition h5, .admonition h6,
+details h1, details h2, details h3,
+details h4, details h5, details h6 {
+    color: var(--bs-light-text-emphasis);
 }
 
 .admonition-title, summary {
@@ -255,8 +304,8 @@ blockquote {
 }
 
 .dropdown-item.open {
-    color: #fff;
-    background-color: #2FA4E7;
+    color: var(--bs-dropdown-link-active-color);
+    background-color: var(--bs-dropdown-link-active-bg);
 }
 
 .dropdown-submenu > .dropdown-menu {
@@ -274,13 +323,13 @@ blockquote {
     border-color: transparent;
     border-style: solid;
     border-width: 5px 0 5px 5px;
-    border-left-color: #ccc;
+    border-left-color: var(--bs-dropdown-link-active-color);
     margin-top: 5px;
     margin-right: -10px;
 }
 
 .dropdown-submenu:hover > a::after {
-    border-left-color: #fff;
+    border-left-color: var(--bs-dropdown-link-active-color);
 }
 
 @media (min-width: 992px) {

diff --git a/mkdocs/themes/mkdocs/css/bootstrap.min.css b/mkdocs/themes/mkdocs/css/bootstrap.min.css
diff --git a/mkdocs/themes/mkdocs/css/bootstrap.min.css.map b/mkdocs/themes/mkdocs/css/bootstrap.min.css.map
diff --git a/mkdocs/themes/mkdocs/js/base.js b/mkdocs/themes/mkdocs/js/base.js
@@ -81,19 +81,6 @@ $(document).ready(function() {
 
     $('table').addClass('table table-striped table-hover');
 
-    // Improve the scrollspy behaviour when users click on a TOC item.
-    $(".bs-sidenav a").on("click", function() {
-        var clicked = this;
-        setTimeout(function() {
-            var active = $('.nav li.active a');
-            active = active[active.length - 1];
-            if (clicked !== active) {
-                $(active).parent().removeClass("active");
-                $(clicked).parent().addClass("active");
-            }
-        }, 50);
-    });
-
     function showInnerDropdown(item) {
         var popup = $(item).next('.dropdown-menu');
         popup.addClass('show');
@@ -156,9 +143,8 @@ $(document).ready(function() {
 
 $(window).on('resize', applyTopPadding);
 
-$('body').scrollspy({
-    target: '.bs-sidebar',
-    offset: 100
+var scrollSpy = new bootstrap.ScrollSpy(document.body, {
+  target: '.bs-sidebar'
 });
 
 /* Prevent disabled links from causing a page reload */

diff --git a/mkdocs/themes/mkdocs/js/bootstrap.bundle.min.js b/mkdocs/themes/mkdocs/js/bootstrap.bundle.min.js
diff --git a/mkdocs/themes/mkdocs/js/bootstrap.bundle.min.js.map b/mkdocs/themes/mkdocs/js/bootstrap.bundle.min.js.map
diff --git a/mkdocs/themes/mkdocs/js/bootstrap.min.js b/mkdocs/themes/mkdocs/js/bootstrap.min.js
diff --git a/mkdocs/themes/mkdocs/keyboard-modal.html b/mkdocs/themes/mkdocs/keyboard-modal.html
@@ -3,7 +3,7 @@
         <div class="modal-content">
             <div class="modal-header">
                 <h4 class="modal-title" id="keyboardModalLabel">{% trans %}Keyboard Shortcuts{% endtrans %}</h4>
-                <button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">{% trans %}Close{% endtrans %}</span></button>
+                <button type="button" class="close" data-bs-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">{% trans %}Close{% endtrans %}</span></button>
             </div>
             <div class="modal-body">
               <table class="table">

diff --git a/mkdocs/themes/mkdocs/nav-sub.html b/mkdocs/themes/mkdocs/nav-sub.html
@@ -1,6 +1,6 @@
 {%- if not nav_item.children %}
 <li>
-    <a href="{{ nav_item.url|url }}" class="dropdown-item{% if nav_item.active %} active{% endif %}">{{ nav_item.title }}</a>
+    <a href="{{ nav_item.url|url }}" class="dropdown-item{% if nav_item.active %} active" aria-current="page{% endif %}">{{ nav_item.title }}</a>
 </li>
 {%- else %}
   <li class="dropdown-submenu">