Merge pull request #684 from paperless-ngx/docs-dark-mode

Documentation dark mode

docs/_static/css/custom.css

@@ -1,9 +1,67 @@
+/* Variables */
+:root {
+  --color-text-body: #5c5962;
+  --color-text-body-light: #fcfcfc;
+  --color-text-anchor: #7253ed;
+  --color-text-alt: rgba(0, 0, 0, 0.3);
+  --color-text-title: #27262b;
+  --color-text-code-inline: #e74c3c;
+  --color-text-code-nt: #062873;
+  --color-text-selection: #b19eff;
+  --color-bg-body: #fcfcfc;
+  --color-bg-body-alt: #f3f6f6;
+  --color-bg-side-nav: #f5f6fa;
+  --color-bg-side-nav-hover: #ebedf5;
+  --color-bg-code-block: var(--color-bg-side-nav);
+  --color-border: #eeebee;
+  --color-btn-neutral-bg: #f3f6f6;
+  --color-btn-neutral-bg-hover: #e5ebeb;
+  --color-success-title: #1abc9c;
+  --color-success-body: #dbfaf4;
+  --color-warning-title: #f0b37e;
+  --color-warning-body: #ffedcc;
+  --color-danger-title: #f29f97;
+  --color-danger-body: #fdf3f2;
+  --color-info-title: #6ab0de;
+  --color-info-body: #e7f2fa;
+}
+
+.dark-mode {
+  --color-text-body: #abb2bf;
+  --color-text-body-light: #9499a2;
+  --color-text-alt: rgba(0255, 255, 255, 0.5);
+  --color-text-title: var(--color-text-anchor);
+  --color-text-code-inline: #abb2bf;
+  --color-text-code-nt: #2063f3;
+  --color-text-selection: #030303;
+  --color-bg-body: #1d1d20 !important;
+  --color-bg-body-alt: #131315;
+  --color-bg-side-nav: #18181a;
+  --color-bg-side-nav-hover: #101216;
+  --color-bg-code-block: #101216;
+  --color-border: #47494f;
+  --color-btn-neutral-bg: #242529;
+  --color-btn-neutral-bg-hover: #101216;
+  --color-success-title: #02120f;
+  --color-success-body: #041b17;
+  --color-warning-title: #1b0e03;
+  --color-warning-body: #371d06;
+  --color-danger-title: #120902;
+  --color-danger-body: #1b0503;
+  --color-info-title: #020608;
+  --color-info-body: #06141e;
+}
+
+* {
+  transition: background-color 0.3s ease, border-color 0.3s ease;
+}
+
 /* Typography */
 body {
   font-family: system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;
   font-size: inherit;
   line-height: 1.4;
-  color: #5c5962;
+  color: var(--color-text-body);
 }
 
 h1, h2, h3, h4, h5, h6 {
@@ -33,6 +91,21 @@ pre, .code, .rst-content .linenodiv pre, .rst-content div[class^=highlight] pre,
   line-height: 1;
 }
 
+footer, footer p {
+  font-size: .8rem;
+}
+
+footer .rst-footer-buttons {
+  font-size: 1rem;
+}
+
+@media (max-width: 400px) {
+  /* break code lines on mobile */
+  pre, code {
+    word-break: break-word;
+  }
+}
+
 
 /* Layout */
 .wy-side-nav-search, .wy-menu-vertical {
@@ -43,7 +116,7 @@ pre, .code, .rst-content .linenodiv pre, .rst-content div[class^=highlight] pre,
   z-index: 0;
   display: flex;
   flex-wrap: wrap;
-  background-color: #f5f6fa
+  background-color: var(--color-bg-side-nav);
 }
 
 .wy-side-scroll {
@@ -64,7 +137,7 @@ pre, .code, .rst-content .linenodiv pre, .rst-content div[class^=highlight] pre,
       width: 248px;
       height: 100%;
       flex-direction: column;
-      border-right: 1px solid #eeebee;
+      border-right: 1px solid var(--color-border);
       align-items:flex-end
   }
 }
@@ -92,13 +165,18 @@ pre, .code, .rst-content .linenodiv pre, .rst-content div[class^=highlight] pre,
 
 
 /* Colors */
+body.wy-body-for-nav,
+.wy-nav-content {
+  background: var(--color-bg-body);
+}
+
 .wy-nav-side {
-  border-right: 1px solid #eeebee;
+  border-right: 1px solid var(--color-border);
 }
 
 .wy-side-nav-search, .wy-nav-top {
-  background: #f5f6fa;
+  background: var(--color-bg-side-nav);
-  border-bottom: 1px solid #eeebee;
+  border-bottom: 1px solid var(--color-border);
 }
 
 .wy-nav-content-wrap {
@@ -106,20 +184,24 @@ pre, .code, .rst-content .linenodiv pre, .rst-content div[class^=highlight] pre,
 }
 
 .wy-side-nav-search > a, .wy-nav-top a, .wy-nav-top i {
-  color: #27262b;
+  color: var(--color-text-title);
+}
+
+.wy-side-nav-search > a:hover, .wy-nav-top a:hover {
+  background: transparent;
 }
 
 .wy-side-nav-search > div.version {
-  color: rgba(0, 0, 0, 0.3);
+  color: var(--color-text-alt)
 }
 
 .wy-side-nav-search > div[role="search"] {
-  border-top: 1px solid #eeebee;
+  border-top: 1px solid var(--color-border);
 }
 
 .wy-menu-vertical li.toctree-l2.current>a, .wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,
 .wy-menu-vertical li.toctree-l3.current>a, .wy-menu-vertical li.toctree-l3.current li.toctree-l4>a {
-  background: #f5f6fa;
+  background: var(--color-bg-side-nav);
 }
 
 .rst-content .highlighted {
@@ -128,23 +210,140 @@ pre, .code, .rst-content .linenodiv pre, .rst-content div[class^=highlight] pre,
   font-weight: 600;
 }
 
+.wy-side-nav-search input[type=text],
+html.writer-html5 .rst-content table.docutils th {
+  color: var(--color-text-body);
+}
+
+.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,
+.wy-table-backed,
+.wy-table-odd td,
+.wy-table-striped tr:nth-child(2n-1) td {
+  background-color: var(--color-bg-body-alt);
+}
+
+.rst-content table.docutils,
+.wy-table-bordered-all,
+html.writer-html5 .rst-content table.docutils th,
+.rst-content table.docutils td,
+.wy-table-bordered-all td,
+hr {
+  border-color: var(--color-border) !important;
+}
+
+::selection {
+  background: var(--color-text-selection);
+}
+
+/* Ridiculous rules are taken from sphinx_rtd */
+.rst-content .admonition-title,
+.wy-alert-title {
+  color: var(--color-text-body-light);
+}
+
+.rst-content .hint,
+.rst-content .important,
+.rst-content .tip,
+.rst-content .wy-alert-success,
+.wy-alert.wy-alert-success {
+  background: var(--color-success-body);
+}
+
+.rst-content .hint .admonition-title,
+.rst-content .hint .wy-alert-title,
+.rst-content .important .admonition-title,
+.rst-content .important .wy-alert-title,
+.rst-content .tip .admonition-title,
+.rst-content .tip .wy-alert-title,
+.rst-content .wy-alert-success .admonition-title,
+.rst-content .wy-alert-success .wy-alert-title,
+.wy-alert.wy-alert-success .rst-content .admonition-title,
+.wy-alert.wy-alert-success .wy-alert-title {
+  background-color: var(--color-success-title);
+}
+
+.rst-content .admonition-todo,
+.rst-content .attention,
+.rst-content .caution,
+.rst-content .warning,
+.rst-content .wy-alert-warning,
+.wy-alert.wy-alert-warning {
+  background: var(--color-warning-body);
+}
+
+.rst-content .admonition-todo .admonition-title,
+.rst-content .admonition-todo .wy-alert-title,
+.rst-content .attention .admonition-title,
+.rst-content .attention .wy-alert-title,
+.rst-content .caution .admonition-title,
+.rst-content .caution .wy-alert-title,
+.rst-content .warning .admonition-title,
+.rst-content .warning .wy-alert-title,
+.rst-content .wy-alert-warning .admonition-title,
+.rst-content .wy-alert-warning .wy-alert-title,
+.rst-content .wy-alert.wy-alert-warning .admonition-title,
+.wy-alert.wy-alert-warning .rst-content .admonition-title,
+.wy-alert.wy-alert-warning .wy-alert-title {
+  background: var(--color-warning-title);
+}
+
+.rst-content .danger,
+.rst-content .error,
+.rst-content .wy-alert-danger,
+.wy-alert.wy-alert-danger {
+  background: var(--color-danger-body);
+}
+
+.rst-content .danger .admonition-title,
+.rst-content .danger .wy-alert-title,
+.rst-content .error .admonition-title,
+.rst-content .error .wy-alert-title,
+.rst-content .wy-alert-danger .admonition-title,
+.rst-content .wy-alert-danger .wy-alert-title,
+.wy-alert.wy-alert-danger .rst-content .admonition-title,
+.wy-alert.wy-alert-danger .wy-alert-title {
+  background: var(--color-danger-title);
+}
+
+.rst-content .note,
+.rst-content .seealso,
+.rst-content .wy-alert-info,
+.wy-alert.wy-alert-info {
+  background: var(--color-info-body);
+}
+
+.rst-content .note .admonition-title,
+.rst-content .note .wy-alert-title,
+.rst-content .seealso .admonition-title,
+.rst-content .seealso .wy-alert-title,
+.rst-content .wy-alert-info .admonition-title,
+.rst-content .wy-alert-info .wy-alert-title,
+.wy-alert.wy-alert-info .rst-content .admonition-title,
+.wy-alert.wy-alert-info .wy-alert-title {
+  background: var(--color-info-title);
+}
+
+
 
 /* Links */
-a, .wy-menu-vertical a, a.icon.icon-home {
+a, a:visited,
-  color: #7253ed;
+.wy-menu-vertical a,
+a.icon.icon-home,
+.wy-menu-vertical li.toctree-l1.current > a.current {
+  color: var(--color-text-anchor);
   text-decoration: none;
 }
 
 a:hover, .wy-breadcrumbs-aside a {
-  color: #7253ed; /* reset */
+  color: var(--color-text-anchor); /* reset */
 }
 
 .rst-versions a, .rst-versions .rst-current-version {
-  color: #7253ed;
+  color: #var(--color-text-anchor);
 }
 
 .wy-nav-content a.reference, .wy-nav-content a:not([class]) {
-  background-image: linear-gradient(#eeebee 0%, #eeebee 100%);
+  background-image: linear-gradient(var(--color-border) 0%, var(--color-border) 100%);
   background-repeat: repeat-x;
   background-position: 0 100%;
   background-size: 1px 1px;
@@ -155,14 +354,17 @@ a:hover, .wy-breadcrumbs-aside a {
   background-size: 1px 1px;
 }
 
-.wy-menu-vertical a:hover {
+.wy-menu-vertical a:hover,
-  background-color: #ebedf5;
+.wy-menu-vertical li.current a:hover,
+.wy-menu-vertical a:active {
+  background: var(--color-bg-side-nav-hover) !important;
+  color: var(--color-text-body);
 }
 
 .wy-menu-vertical li.toctree-l1.current>a,
 .wy-menu-vertical li.current>a,
 .wy-menu-vertical li.on a {
-  background-color: #ebedf5;
+  background-color: var(--color-bg-side-nav-hover);
   border: none;
   font-weight: normal;
 }
@@ -171,10 +373,6 @@ a:hover, .wy-breadcrumbs-aside a {
   background-color: inherit;
 }
 
-.wy-menu-vertical li.current a:hover {
-  background-color: #ebedf5 !important;
-}
-
 .wy-menu-vertical li.current a {
   border-right: none;
 }
@@ -188,7 +386,7 @@ a:hover, .wy-breadcrumbs-aside a {
 .wy-menu-vertical li.toctree-l8 a,
 .wy-menu-vertical li.toctree-l9 a,
 .wy-menu-vertical li.toctree-l10 a {
-  color: #5c5962;
+  color: var(--color-text-body);
 }
 
 a.image-reference, a.image-reference:hover {
@@ -204,8 +402,8 @@ a.image-reference img {
 .rst-content code, .rst-content tt, code {
   padding: 0.25em;
   font-weight: 400;
-  background-color: #f5f6fa;
+  background-color: var(--color-bg-code-block);
-  border: 1px solid #eeebee;
+  border: 1px solid var(--color-border);
   border-radius: 4px;
 }
 
@@ -214,22 +412,41 @@ a.image-reference img {
   margin-top: 0;
   margin-bottom: 0.75rem;
   overflow-x: auto;
-  background-color: #f5f6fa;
+  background-color: var(--color-bg-side-nav);
+  border-color: var(--color-border);
   border-radius: 4px;
   box-shadow: none;
 }
 
-.rst-content .admonition-title, .wy-alert-title {
+.rst-content .admonition-title,
+.rst-content div.admonition,
+.wy-alert-title {
   padding: 10px 12px;
   border-top-left-radius: 4px;
   border-top-right-radius: 4px;
 }
 
+.highlight .go {
+  color: inherit;
+}
+
+.highlight .nt {
+  color: var(--color-text-code-nt);
+}
+
+.rst-content code.literal,
+.rst-content tt.literal {
+  border-color: var(--color-border);
+  background-color: var(--color-border);
+  color: var(--color-text-code-inline)
+}
+
 
 /* Search */
 .wy-side-nav-search input[type=text] {
   border: none;
-  background-color: #f5f6fa;
+  border-radius: 0;
+  background-color: transparent;
   font-family: inherit;
   font-size: .85rem;
   box-shadow: none;
@@ -248,7 +465,7 @@ a.image-reference img {
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
   content: "\f002";
-  color: #dde0ee;
+  color: var(--color-text-alt);
   position: absolute;
   left: 1.5rem;
   top: .7rem;
@@ -280,7 +497,6 @@ a.image-reference img {
   padding: 10px 12px;
 }
 
-
 /* Buttons */
 .btn {
   display: inline-block;
@@ -291,7 +507,7 @@ a.image-reference img {
   font-size: inherit;
   font-weight: 500;
   line-height: 1.5;
-  color: #7253ed;
+  color: #var(--color-text-anchor);
   text-decoration: none;
   vertical-align: baseline;
   background-color: #f7f7f7;
@@ -310,7 +526,17 @@ a.image-reference img {
 }
 
 .rst-content .btn-neutral, .rst-content .btn span.fa {
-  color: #5c5962 !important;
+  color: var(--color-text-body) !important;
+}
+
+.btn-neutral {
+  background-color: var(--color-btn-neutral-bg) !important;
+  color: var(--color-btn-neutral-text) !important;
+  border: 1px solid var(--color-btn-neutral-bg);
+}
+
+.btn:hover, .btn-neutral:hover {
+  background-color: var(--color-btn-neutral-bg-hover) !important;
 }
 
 
@@ -336,5 +562,27 @@ a.image-reference img {
 .wy-nav-top > i {
   font-size: 24px;
   padding: 8px 0 0 2px;
-  color:#7253ed;
+  color:#var(--color-text-anchor);
+}
+
+.rst-content table.docutils td,
+.rst-content table.docutils th,
+.rst-content table.field-list td,
+.rst-content table.field-list th,
+.wy-table td,
+.wy-table th {
+  padding: 8px 14px;
+}
+
+.dark-mode-toggle {
+  position: absolute;
+  top: 14px;
+  right: 15px;
+  height: 20px;
+  width: 20px;
+  z-index: 1000;
+  border: none;
+  background-color: transparent;
+  color: inherit;
+  opacity: 0.7;
 }

docs/_static/js/darkmode.js

@@ -0,0 +1,47 @@
+let toggleButton;
+let icon;
+
+function load() {
+	"use strict";
+
+	toggleButton = document.createElement("button");
+	toggleButton.setAttribute("title", "Toggle dark mode");
+	toggleButton.classList.add("dark-mode-toggle");
+	icon = document.createElement("i");
+	icon.classList.add("fa", darkModeState ? "fa-sun-o" : "fa-moon-o");
+	toggleButton.appendChild(icon);
+	document.body.prepend(toggleButton);
+
+	// Listen for changes in the OS settings
+	// addListener is used because older versions of Safari don't support addEventListener
+	// prefersDarkQuery set in <head>
+	if (prefersDarkQuery) {
+		prefersDarkQuery.addListener(function (evt) {
+			toggleDarkMode(evt.matches);
+		});
+	}
+
+	// Initial setting depending on the prefers-color-mode or localstorage
+	// darkModeState should be set in the document <head> to prevent flash
+	if (darkModeState == undefined) darkModeState = false;
+	toggleDarkMode(darkModeState);
+
+	// Toggles the "dark-mode" class on click and sets localStorage state
+	toggleButton.addEventListener("click", () => {
+		darkModeState = !darkModeState;
+
+		toggleDarkMode(darkModeState);
+		localStorage.setItem("dark-mode", darkModeState);
+	});
+}
+
+function toggleDarkMode(state) {
+	document.documentElement.classList.toggle("dark-mode", state);
+	document.documentElement.classList.toggle("light-mode", !state);
+	icon.classList.remove("fa-sun-o");
+	icon.classList.remove("fa-moon-o");
+	icon.classList.add(state ? "fa-sun-o" : "fa-moon-o");
+	darkModeState = state;
+}
+
+document.addEventListener("DOMContentLoaded", load);

docs/_templates/layout.html

@@ -0,0 +1,13 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+    <script>
+        // MediaQueryList object
+        const prefersDarkQuery = window.matchMedia("(prefers-color-scheme: dark)");
+        const lsDark = localStorage.getItem("dark-mode");
+        let darkModeState = lsDark !== null ? lsDark == "true" : prefersDarkQuery.matches;
+
+        document.documentElement.classList.toggle("dark-mode", darkModeState);
+        document.documentElement.classList.toggle("light-mode", !darkModeState);
+    </script>
+    {{ super() }}
+{% endblock %}

docs/conf.py

@@ -15,7 +15,7 @@ extensions = [
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-# templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix of source filenames.
 source_suffix = ".rst"
@@ -125,6 +125,10 @@ html_css_files = [
     "css/custom.css",
 ]
 
+html_js_files = [
+    "js/darkmode.js",
+]
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.