Docs automatic light/dark mode (#6287)

Signed-off-by: Glenn Jocher <glenn.jocher@ultralytics.com>
Co-authored-by: Sergiu Waxmann <47978446+sergiuwaxmann@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

docs/README.md

@@ -2,7 +2,7 @@
 
 Ultralytics Docs are deployed to [https://docs.ultralytics.com](https://docs.ultralytics.com).
 
-[![pages-build-deployment](https://github.com/ultralytics/docs/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/ultralytics/docs/actions/workflows/pages/pages-build-deployment)  [![Check Broken links](https://github.com/ultralytics/docs/actions/workflows/links.yml/badge.svg?branch=gh-pages)](https://github.com/ultralytics/docs/actions/workflows/links.yml)
+[![pages-build-deployment](https://github.com/ultralytics/docs/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/ultralytics/docs/actions/workflows/pages/pages-build-deployment)  [![Check Broken links](https://github.com/ultralytics/docs/actions/workflows/links.yml/badge.svg)](https://github.com/ultralytics/docs/actions/workflows/links.yml)
 
 ### Install Ultralytics package
 

docs/build_docs.py

@@ -51,16 +51,31 @@ def build_docs():
 
 
 def update_html_links():
-    """Update href links in HTML files to remove '.md'."""
+    """Update href links in HTML files to remove '.md', excluding links starting with 'https://'."""
     html_files = SITE.rglob('*.html')
+    total_updated_links = 0
+
     for html_file in html_files:
         with open(html_file, 'r+', encoding='utf-8') as file:
             content = file.read()
-            updated_content = re.sub(r'href="([^"]+)\.md"', r'href="\1"', content)
+            # Find all links to be updated, excluding those starting with 'https://'
+            links_to_update = re.findall(r'href="(?!https://)([^"]+)\.md"', content)
+
+            # Update the content and count the number of links updated
+            updated_content, number_of_links_updated = re.subn(r'href="(?!https://)([^"]+)\.md"', r'href="\1"', content)
+            total_updated_links += number_of_links_updated
+
+            # Write the updated content back to the file
             file.seek(0)
             file.write(updated_content)
             file.truncate()
 
+            # Print updated links for this file
+            for link in links_to_update:
+                print(f'Updated link in {html_file}: {link}')
+
+    print(f'Total number of links updated: {total_updated_links}')
+
 
 def main():
     # Build the docs

docs/mkdocs.yml

@@ -23,16 +23,24 @@ theme:
   #  text: Helvetica
   #  code: Roboto Mono
   palette:
-    - scheme: default  # light mode
+    - media: "(prefers-color-scheme)"
-      # primary: grey
       toggle:
-        icon: material/toggle-switch
+        icon: material/brightness-auto
-        name: Switch to dark mode
-    - scheme: slate  # dark mode
-      # primary: black
-      toggle:
-        icon: material/toggle-switch-off-outline
         name: Switch to light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
   features:
     - announce.dismiss
     - content.action.edit
@@ -154,7 +162,16 @@ nav:
           - Segment: tasks/segment.md
           - Classify: tasks/classify.md
           - Pose: tasks/pose.md
-      - Ultralytics 文档: https://docs.ultralytics.com/zh/
+      - Languages:
+          - 🇬🇧&nbsp English: https://docs.ultralytics.com/
+          - 🇨🇳&nbsp 简体中文: https://docs.ultralytics.com/zh/
+          - 🇰🇷&nbsp 한국어: https://docs.ultralytics.com/ko/
+          - 🇯🇵&nbsp 日本語: https://docs.ultralytics.com/ja/
+          - 🇷🇺&nbsp Русский: https://docs.ultralytics.com/ru/
+          - 🇩🇪&nbsp Deutsch: https://docs.ultralytics.com/de/
+          - 🇫🇷&nbsp Français: https://docs.ultralytics.com/fr/
+          - 🇪🇸&nbsp Español: https://docs.ultralytics.com/es/
+          - 🇵🇹&nbsp Português: https://docs.ultralytics.com/pt/
   - Quickstart: quickstart.md
   - Modes:
       - modes/index.md

docs/mkdocs_de.yml

@@ -23,16 +23,24 @@ theme:
   #  text: Helvetica
   #  code: Roboto Mono
   palette:
-    - scheme: default  # light mode
+    - media: "(prefers-color-scheme)"
-      # primary: grey
       toggle:
-        icon: material/toggle-switch
+        icon: material/brightness-auto
-        name: Switch to dark mode
-    - scheme: slate  # dark mode
-      # primary: black
-      toggle:
-        icon: material/toggle-switch-off-outline
         name: Switch to light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
   features:
     - announce.dismiss
     - content.action.edit
@@ -110,6 +118,8 @@ extra:
 
 extra_css:
   - 'stylesheets/style.css'
+extra_javascript:
+  - 'javascript/extra.js'
 
 markdown_extensions:
   - admonition

docs/mkdocs_es.yml

@@ -23,16 +23,24 @@ theme:
   #  text: Helvetica
   #  code: Roboto Mono
   palette:
-    - scheme: default  # light mode
+    - media: "(prefers-color-scheme)"
-      # primary: grey
       toggle:
-        icon: material/toggle-switch
+        icon: material/brightness-auto
-        name: Switch to dark mode
-    - scheme: slate  # dark mode
-      # primary: black
-      toggle:
-        icon: material/toggle-switch-off-outline
         name: Switch to light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
   features:
     - announce.dismiss
     - content.action.edit
@@ -110,6 +118,8 @@ extra:
 
 extra_css:
   - 'stylesheets/style.css'
+extra_javascript:
+  - 'javascript/extra.js'
 
 markdown_extensions:
   - admonition

docs/mkdocs_fr.yml

@@ -23,16 +23,24 @@ theme:
   #  text: Helvetica
   #  code: Roboto Mono
   palette:
-    - scheme: default  # light mode
+    - media: "(prefers-color-scheme)"
-      # primary: grey
       toggle:
-        icon: material/toggle-switch
+        icon: material/brightness-auto
-        name: Switch to dark mode
-    - scheme: slate  # dark mode
-      # primary: black
-      toggle:
-        icon: material/toggle-switch-off-outline
         name: Switch to light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
   features:
     - announce.dismiss
     - content.action.edit
@@ -110,6 +118,8 @@ extra:
 
 extra_css:
   - 'stylesheets/style.css'
+extra_javascript:
+  - 'javascript/extra.js'
 
 markdown_extensions:
   - admonition

docs/mkdocs_ja.yml

@@ -23,16 +23,24 @@ theme:
   #  text: Helvetica
   #  code: Roboto Mono
   palette:
-    - scheme: default  # light mode
+    - media: "(prefers-color-scheme)"
-      # primary: grey
       toggle:
-        icon: material/toggle-switch
+        icon: material/brightness-auto
-        name: Switch to dark mode
-    - scheme: slate  # dark mode
-      # primary: black
-      toggle:
-        icon: material/toggle-switch-off-outline
         name: Switch to light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
   features:
     - announce.dismiss
     - content.action.edit
@@ -110,6 +118,8 @@ extra:
 
 extra_css:
   - 'stylesheets/style.css'
+extra_javascript:
+  - 'javascript/extra.js'
 
 markdown_extensions:
   - admonition

docs/mkdocs_ko.yml

@@ -23,16 +23,24 @@ theme:
   #  text: Helvetica
   #  code: Roboto Mono
   palette:
-    - scheme: default  # light mode
+    - media: "(prefers-color-scheme)"
-      # primary: grey
       toggle:
-        icon: material/toggle-switch
+        icon: material/brightness-auto
-        name: Switch to dark mode
-    - scheme: slate  # dark mode
-      # primary: black
-      toggle:
-        icon: material/toggle-switch-off-outline
         name: Switch to light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
   features:
     - announce.dismiss
     - content.action.edit
@@ -110,6 +118,8 @@ extra:
 
 extra_css:
   - 'stylesheets/style.css'
+extra_javascript:
+  - 'javascript/extra.js'
 
 markdown_extensions:
   - admonition

docs/mkdocs_pt.yml

@@ -23,16 +23,24 @@ theme:
   #  text: Helvetica
   #  code: Roboto Mono
   palette:
-    - scheme: default  # light mode
+    - media: "(prefers-color-scheme)"
-      # primary: grey
       toggle:
-        icon: material/toggle-switch
+        icon: material/brightness-auto
-        name: Switch to dark mode
-    - scheme: slate  # dark mode
-      # primary: black
-      toggle:
-        icon: material/toggle-switch-off-outline
         name: Switch to light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
   features:
     - announce.dismiss
     - content.action.edit
@@ -110,6 +118,8 @@ extra:
 
 extra_css:
   - 'stylesheets/style.css'
+extra_javascript:
+  - 'javascript/extra.js'
 
 markdown_extensions:
   - admonition

docs/mkdocs_ru.yml

@@ -23,16 +23,24 @@ theme:
   #  text: Helvetica
   #  code: Roboto Mono
   palette:
-    - scheme: default  # light mode
+    - media: "(prefers-color-scheme)"
-      # primary: grey
       toggle:
-        icon: material/toggle-switch
+        icon: material/brightness-auto
-        name: Switch to dark mode
-    - scheme: slate  # dark mode
-      # primary: black
-      toggle:
-        icon: material/toggle-switch-off-outline
         name: Switch to light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
   features:
     - announce.dismiss
     - content.action.edit
@@ -110,6 +118,8 @@ extra:
 
 extra_css:
   - 'stylesheets/style.css'
+extra_javascript:
+  - 'javascript/extra.js'
 
 markdown_extensions:
   - admonition

docs/mkdocs_zh.yml

@@ -23,16 +23,24 @@ theme:
   #  text: Helvetica
   #  code: Roboto Mono
   palette:
-    - scheme: default  # light mode
+    - media: "(prefers-color-scheme)"
-      # primary: grey
       toggle:
-        icon: material/toggle-switch
+        icon: material/brightness-auto
-        name: Switch to dark mode
-    - scheme: slate  # dark mode
-      # primary: black
-      toggle:
-        icon: material/toggle-switch-off-outline
         name: Switch to light mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
   features:
     - announce.dismiss
     - content.action.edit
@@ -110,6 +118,8 @@ extra:
 
 extra_css:
   - 'stylesheets/style.css'
+extra_javascript:
+  - 'javascript/extra.js'
 
 markdown_extensions:
   - admonition

docs/overrides/javascript/extra.js

@@ -0,0 +1,49 @@
+// Function that applies light/dark theme based on the user's preference
+const applyAutoTheme = () => {
+  // Determine the user's preferred color scheme
+  const prefersLight = window.matchMedia("(prefers-color-scheme: light)").matches;
+  const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+
+  // Apply the appropriate attributes based on the user's preference
+  if (prefersLight) {
+    document.body.setAttribute("data-md-color-scheme", "default");
+    document.body.setAttribute("data-md-color-primary", "indigo");
+  } else if (prefersDark) {
+    document.body.setAttribute("data-md-color-scheme", "slate");
+    document.body.setAttribute("data-md-color-primary", "black");
+  }
+};
+
+// Function that checks and applies light/dark theme based on the user's preference (if auto theme is enabled)
+function checkAutoTheme() {
+  // Retrieve the palette from local storage
+  const palette = localStorage.getItem("/.__palette");
+  if (palette) {
+    // Check if the palette's index is 0 (auto theme)
+    const paletteObj = JSON.parse(palette);
+    if (paletteObj && paletteObj.index === 0) {
+      applyAutoTheme();
+    }
+  }
+}
+// ! No need to run the function when the script loads as by default the theme is determined by the user's preference (if auto theme is enabled)
+// checkAutoTheme();
+// Run the function when the user's preference changes (when the user changes their system theme)
+window.matchMedia("(prefers-color-scheme: light)").addEventListener("change", checkAutoTheme);
+window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", checkAutoTheme);
+
+// Re-run the function when the palette changes (e.g. user switched from dark theme to auto theme)
+// ! We can't use window.addEventListener("storage", checkAutoTheme) because it will NOT be triggered on the current tab
+// ! So we have to use the following workaround:
+// Get the palette input for auto theme
+var autoThemeInput = document.getElementById("__palette_1");
+if (autoThemeInput) {
+  // Add a click event listener to the input
+  autoThemeInput.addEventListener("click", function () {
+    // Check if the auto theme is selected
+    if (autoThemeInput.checked) {
+      // Re-run the function after a short delay (to ensure that the palette has been updated)
+      setTimeout(applyAutoTheme);
+    }
+  });
+}

docs/overrides/stylesheets/style.css

@@ -27,8 +27,8 @@ th, td {
 }
 
 /* dark mode alternating table bg colors */
-[data-md-color-scheme="slate"] .md-typeset__table tr:nth-child(2n) {
+body.md-theme--slate .md-typeset__table tr:nth-child(2n) {
-    background-color: hsla(var(--md-hue),25%,25%,1)
+    background-color: hsla(207, 26%, 17%, 1);
 }
 /* Table format like GitHub ----------------------------------------------------------------------------------------- */