Skip to content

Enable Dark Mode

Introduction

This guide will walk you through the steps to add a dark mode toggle to the OVI-GC Knowledge Base, allowing users to switch between light and dark themes for better readability and user experience.

Prerequisites

Ensure you have MkDocs and the material theme installed. You can install them using pip if you haven't already:
```
pip install mkdocs mkdocs-material
```

Step 1: Update `mkdocs.yml` Configuration

Open your mkdocs.yml file.

Update the theme section to include dark mode options. Here's the updated configuration:

site_name: "OVI-GC Knowledge Base"
theme:
  name: material
  features:
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.tabs
    - navigation.sections
    - toc.integrate
    - navigation.top
    - search.suggest
    - search.highlight
    - content.tabs.link
    - content.code.annotation
    - content.code.copy
  palette:
    - scheme: default
      primary: deep-orange  # Deeper Orange
      accent: deep-purple   # Medium to Dark Purple
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    - scheme: slate
      primary: deep-orange  # Deeper Orange
      accent: deep-purple   # Medium to Dark Purple
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode

markdown_extensions:
  - admonition
  - codehilite
  - footnotes
  - meta
  - toc
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

plugins:
  - search
  - mermaid2:
      arguments:
        config: '{"theme":"forest"}'
        javascript: 'https://unpkg.com/mermaid@10.4.0/dist/mermaid.min.js'

extra_javascript:
  - js/mermaid-init.js
  - js/theme-toggle.js

Step 2: Create a JavaScript File for Theme Toggling

Create a directory named js inside your docs folder.
Inside the js directory, create a file named theme-toggle.js.

Add the following content to theme-toggle.js:

document.addEventListener("DOMContentLoaded", function () {
    const themeToggle = document.querySelector("button.md-header-nav__button");

    if (themeToggle) {
        themeToggle.addEventListener("click", function () {
            if (document.body.classList.contains("md-scheme-default")) {
                document.body.classList.remove("md-scheme-default");
                document.body.classList.add("md-scheme-slate");
            } else {
                document.body.classList.remove("md-scheme-slate");
                document.body.classList.add("md-scheme-default");
            }
        });
    }
});

Step 3: Serve or Build Your MkDocs Site

To preview your changes locally, use the following command:
```
mkdocs serve
```
To build your site for deployment, use:
```
mkdocs build
```

Conclusion

By following these steps, you will add a dark mode toggle to the OVI-GC Knowledge Base. This feature enhances the user experience by allowing users to switch between light and dark themes according to their preference.

If you encounter any issues or have further questions, please reach out to the documentation team.