Add Dark Mode Support

docs/_markbind/boilerplates/codeAndOutput.md

@@ -20,7 +20,7 @@
 %%OUTPUT:%%
 <div class="indented">
 
-<box border-left-color="grey" background-color="white">
+<box border-left-color="grey">
 
 {{ code | safe }}
 </box>

docs/_markbind/boilerplates/codeAndOutputCode.md

@@ -20,7 +20,7 @@
 %%OUTPUT:%%
 <div class="indented">
 
-<box border-left-color="grey" background-color="white">
+<box border-left-color="grey">
 
 {{ code | safe }}
 </box>

docs/_markbind/boilerplates/codeAndOutputSeparate.md

@@ -20,7 +20,7 @@
 %%OUTPUT:%%
 <div class="indented">
 
-<box border-left-color="grey" background-color="white">
+<box border-left-color="grey">
 
 {{ output | safe }}
 </box>

docs/_markbind/layouts/userGuide.md

@@ -31,6 +31,7 @@
   * [Using Plugins]({{baseUrl}}/userGuide/usingPlugins.html)
   * [Making the Site Searchable]({{baseUrl}}/userGuide/makingTheSiteSearchable.html)
   * [Applying Themes]({{baseUrl}}/userGuide/themes.html)
+  * [Dark Mode]({{baseUrl}}/userGuide/darkMode.html)
   * [Deploying the Site]({{baseUrl}}/userGuide/deployingTheSite.html)
   * [MarkBind in the Project Workflow]({{baseUrl}}/userGuide/markBindInTheProjectWorkflow.html)
   * [Redirecting to a Custom 404 Page]({{baseUrl}}/userGuide/redirectingToACustom404Page.html)

docs/css/main.css

@@ -1,10 +1,3 @@
-mark {
-    background-color: #ff0;
-    border-radius: 5px;
-    padding-top: 0;
-    padding-bottom: 0;
-}
-
 .indented {
     padding-left: 20px;
 }
@@ -74,7 +67,7 @@ mark {
 }
 
 #site-nav {
-    border-right: 1px solid lightgrey;
+    border-right: 1px solid var(--bs-border-color);
     padding-bottom: 20px;
     z-index: 999;
 }
@@ -89,7 +82,7 @@ mark {
 }
 
 #page-nav {
-    border-left: 1px solid lightgrey;
+    border-left: 1px solid var(--bs-border-color);
 }
 
 @media screen and (width <= 1299.98px) {

docs/dg-site.json

@@ -2,6 +2,7 @@
   "baseUrl": "/devdocs",
   "titlePrefix": "MarkBind",
   "style": {
+    "darkMode": true,
     "codeTheme": "light"
   },
   "pages": [

docs/njk/common.njk

@@ -1,10 +1,10 @@
 {% macro previous_next(previous_page, next_page) %}
 <div class="clearfix">
 {% if previous_page != ''%}
-<span class="float-start"><a class="btn btn-light" href="{{ previous_page }}.html"><md>:far-arrow-alt-circle-left: <include src="{{ previous_page }}.md#title" inline /></md></a></span>
+<span class="float-start"><a class="btn" href="{{ previous_page }}.html"><md>:far-arrow-alt-circle-left: <include src="{{ previous_page }}.md#title" inline /></md></a></span>
 {% endif %}
 {% if next_page != ''%}
-<span class="float-end"><a class="btn btn-light" href="{{ next_page }}.html"><md><include src="{{ next_page }}.md#title" inline /> :far-arrow-alt-circle-right:</md></a></span>
+<span class="float-end"><a class="btn" href="{{ next_page }}.html"><md><include src="{{ next_page }}.md#title" inline /> :far-arrow-alt-circle-right:</md></a></span>
 {% endif %}
 </div>
 <br>

docs/site.json

@@ -3,7 +3,8 @@
   "timeZone": "Asia/Singapore",
   "titlePrefix": "MarkBind",
   "style": {
-    "codeTheme": "light"
+    "codeTheme": "light",
+    "darkMode": true
   },
   "pages": [
     {

docs/userGuide/darkMode.md

@@ -0,0 +1,65 @@
+{% set title = "Dark Mode" %}
+{% set filename = "darkMode" %}
+<span id="title" class="d-none">{{ title }}</span>
+
+<frontmatter>
+  title: "User Guide: {{ title }}"
+  layout: userGuide.md
+</frontmatter>
+
+<span id="link" class="d-none">
+<md>[_User Guide → {{ title }}_]({{ filename }}.html)</md>
+</span>
+
+# Dark Mode
+
+<div class="lead" id="overview">
+
+**MarkBind now supports _dark mode_**
+
+</div>
+
+#### Enabling Dark Mode
+
+You can enable dark mode for your site by using the [`style.darkMode` property](siteJsonFile.html#style) of your `site.json` configuration file.
+
+```json {heading="site.json"}
+{
+  "style": {
+    "darkMode": true
+  }
+}
+```
+
+Enabling dark mode causes the site to default to the user's system preference.
+Readers can also switch between light and dark mode at any time using the
+`<dark-mode-toggle/>` component, which appears in the navigation bar to the
+right of the search bar. This setting will be remembered for future visits to
+the site.
+
+#### Adapting Existing Sites to Dark Mode
+
+##### Updating stylesheet
+
+After enabling dark mode, replace your `/css/main.css` in your markbind site
+directory with the latest version [here](https://github.com/yihao03/markbind/raw/05d686b4375078a6d4200e15dcef4831bd37f61e/docs/css/main.css)
+to override the default Bootstrap styles with the new dark mode compatible styles.
+
+##### Adapting your contents
+
+We recognise that some of your existing contents e.g. images with transparent
+backgrounds and diagrams might have some visibility issues when viewed in dark
+mode. We recommend that:
+
+- You wrap your images in a `<box>` tag with light background to improve visibility.
+
+    ```md
+    <box background-color="#f8f9fa">
+      your existing content
+    </box>
+    ```
+
+- Adapt your diagrams to use colours that are more visible in both modes
+
+{% from "njk/common.njk" import previous_next %}
+{{ previous_next('themes', 'deployingTheSite') }}

docs/userGuide/deployingTheSite.md

@@ -581,4 +581,4 @@ For more information on Surge, you may refer to [Surge's docs](https://surge.sh/
 </panel>
 
 {% from "njk/common.njk" import previous_next %}
-{{ previous_next('themes', 'markBindInTheProjectWorkflow') }}
+{{ previous_next('darkMode', 'markBindInTheProjectWorkflow') }}

docs/userGuide/markBindSyntaxOverview.md

@@ -118,7 +118,7 @@ MarkBind has Vue.js components built on the popular [BootStrap](https://getboots
 %%OUTPUT:%%
 <div class="indented">
 
-<box border-left-color="grey" background-color="white">
+<box border-left-color="grey">
 
 <ul>
 {% for item in [1, 2, 3, 4] %}

docs/userGuide/siteJsonFile.md

@@ -21,6 +21,7 @@ Here is a typical `site.json` file:
   "titlePrefix": "FooBar Dev Docs",
   "titleSuffix": "FooBar",
   "style": {
+    darkMode: true,
     "bootstrapTheme": "bootswatch-cerulean",
     "codeTheme": "light",
     "codeLineNumbers": true
@@ -113,6 +114,10 @@ Note: `baseUrl` does not support [live preview](glossary.md#live-preview) as the
 
 _(Optional)_ **The styling options to be applied to the site.** This includes:
 
+* `darkMode`
+  * [Optional. Default: `false`](/userGuide/darkMode.html#enabling-dark-mode)<br>
+  Toggles whether to enable dark mode for the site.
+
 * **`bootstrapTheme`**
  _(Optional)_ The theme for the generated site.<br>
   Uses the default Bootstrap theme if not specified. See [User Guide: Themes](themes.html) for more details.

docs/userGuide/syntax/darkModeToggle.md

@@ -0,0 +1,32 @@
+## Dark Mode Toggle
+
+<div id="content">
+
+The `dark-mode-toggle` component provides a button that lets readers switch between light and dark themes.
+
+****Usage****
+
+Add `<dark-mode-toggle></dark-mode-toggle>` to your layout or navbar file. The component is only rendered when dark mode is enabled for the site (via the `enableDarkMode` site property).
+
+****How It Works****
+
+- Defaults to the user's OS-level `prefers-color-scheme` setting
+- Persists the user's choice in `localStorage` under the key `markbind-theme`
+
+****Placing in the Navbar****
+
+The toggle is automatically included inside the navbar when dark mode is enabled. You can also place it manually anywhere on the page:
+
+</div>
+
+<div id="short">
+
+```html
+<dark-mode-toggle></dark-mode-toggle>
+```
+</div>
+
+<div id="examples" class="d-none">
+
+You can see an example of the dark mode toggle in the navbar at the top of this page.
+</div>

docs/userGuide/syntax/fullSyntaxSet.njk

@@ -44,6 +44,7 @@
   siteNavigationMenus : ['Site Navigation Menus', 'site-navigation-menus', ['navigation', 'reader-facing']],
   pageNavigationMenus : ['Page Navigation Menus', 'page-navigation-menus', ['navigation', 'reader-facing']],
   scrollTopButton : ['Scroll To Top Button', 'scroll-to-top-button', ['navigation', 'reader-facing']],
+  darkModeToggle : ['Dark Mode Toggle', 'dark-mode-toggle', ['navigation', 'reader-facing']],
   questions : ['Questions and Quizzes', 'questions-and-quizzes', ['others', 'reader-facing']]
 } %}
 

docs/userGuide/themes.md

@@ -73,4 +73,4 @@ Currently, MarkBind supports all light themes from [Bootswatch](https://bootswat
 </div>
 
 {% from "njk/common.njk" import previous_next %}
-{{ previous_next('makingTheSiteSearchable', 'deployingTheSite') }}
+{{ previous_next('makingTheSiteSearchable', 'darkMode') }}

packages/cli/test/functional/test_site/expected/bugs/index.html

@@ -1,7 +1,8 @@
 <!DOCTYPE html>
-<html>
+<html data-dark-mode="false" data-code-theme="dark">
 
 <head>
+  <script src="/test_site/markbind/js/theme-manager.js"></script>
 
   <meta name="default-head-top">
   <script src="/test_site/headFiles/customScriptTop.js"></script>
@@ -14,7 +15,11 @@
   <link rel="stylesheet" href="/test_site/markbind/css/bootstrap.min.css">
   <link rel="stylesheet" href="/test_site/markbind/fontawesome/css/all.min.css">
   <link rel="stylesheet" href="/test_site/markbind/glyphicons/css/bootstrap-glyphicons.min.css">
-  <link rel="stylesheet" href="/test_site/markbind/css/codeblock-dark.min.css">
+
+
+  <link rel="stylesheet" id="markbind-highlight-light" href="/test_site/markbind/css/codeblock-light.min.css">
+  <link rel="stylesheet" id="markbind-highlight-dark" href="/test_site/markbind/css/codeblock-dark.min.css">
+  <script src="/test_site/markbind/js/code-theme.js"></script>
   <link rel="stylesheet" href="/test_site/markbind/css/markbind.min.css">
   <link rel="stylesheet" href="/test_site/plugins/testMarkbindPlugin/testMarkbindPluginStylesheet.css">
   <link rel="stylesheet" href="/test_site/plugins/web3Form/web-3-form.css">

packages/cli/test/functional/test_site/expected/index.html

@@ -1,7 +1,8 @@
 <!DOCTYPE html>
-<html>
+<html data-dark-mode="false" data-code-theme="dark">
 
 <head>
+  <script src="/test_site/markbind/js/theme-manager.js"></script>
 
   <meta name="default-head-top">
   <script src="/test_site/headFiles/customScriptTop.js"></script>
@@ -14,7 +15,11 @@
   <link rel="stylesheet" href="/test_site/markbind/css/bootstrap.min.css">
   <link rel="stylesheet" href="/test_site/markbind/fontawesome/css/all.min.css">
   <link rel="stylesheet" href="/test_site/markbind/glyphicons/css/bootstrap-glyphicons.min.css">
-  <link rel="stylesheet" href="/test_site/markbind/css/codeblock-dark.min.css">
+
+
+  <link rel="stylesheet" id="markbind-highlight-light" href="/test_site/markbind/css/codeblock-light.min.css">
+  <link rel="stylesheet" id="markbind-highlight-dark" href="/test_site/markbind/css/codeblock-dark.min.css">
+  <script src="/test_site/markbind/js/code-theme.js"></script>
   <link rel="stylesheet" href="/test_site/markbind/css/markbind.min.css">
   <link rel="stylesheet" href="/test_site/plugins/testMarkbindPlugin/testMarkbindPluginStylesheet.css">
   <link rel="stylesheet" href="/test_site/plugins/web3Form/web-3-form.css">

packages/cli/test/functional/test_site/expected/markbind/js/code-theme.js

@@ -0,0 +1,20 @@
+/**
+ * Loaded immediately after the highlight stylesheet <link> elements.
+ * Disables the stylesheet that doesn't match the active theme.
+ *
+ * Reads from window.__MARKBIND_THEME__ (set by theme-manager.js) or falls back
+ * to the data-code-theme attribute on <html> set by the server.
+ */
+(function () {
+  const theme = window.__MARKBIND_THEME__
+    || document.documentElement.getAttribute('data-code-theme')
+    || 'light';
+
+  const lightSheet = document.getElementById('markbind-highlight-light');
+  const darkSheet = document.getElementById('markbind-highlight-dark');
+
+  if (lightSheet && darkSheet) {
+    lightSheet.disabled = theme !== 'light';
+    darkSheet.disabled = theme !== 'dark';
+  }
+}());

packages/cli/test/functional/test_site/expected/markbind/js/theme-manager.js

@@ -0,0 +1,26 @@
+/**
+ * Loaded as early as possible in <head> to prevent flash of unstyled content (FOUC).
+ * Sets data-bs-theme on <html> before any stylesheets are applied.
+ *
+ * Reads from <html> attributes set by the server:
+ *   - data-dark-mode="true|false"
+ */
+(function () {
+  if (document.documentElement.getAttribute('data-dark-mode') !== 'true') return;
+
+  const STORAGE_KEY = 'markbind-theme';
+  let stored;
+  try { stored = localStorage.getItem(STORAGE_KEY); } catch (e) { /* ignore */ }
+
+  let theme;
+  if (stored === 'dark' || stored === 'light') {
+    theme = stored;
+  } else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+    theme = 'dark';
+  } else {
+    theme = 'light';
+  }
+  document.documentElement.setAttribute('data-bs-theme', theme);
+  window.__MARKBIND_THEME__ = theme;
+  window.__MARKBIND_DARK_MODE__ = true;
+}());