♻️ Dark mode rewrite

CHANGELOG.md

@@ -25,9 +25,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ### Changed
 
 - ⚠️ Required Hugo version is now 0.87.0 or later
-- ⚠️ Author and logo images are now Hugo assets
+- ⚠️ Complete rewrite of dark mode to allow more flexibile configuration
+- ⚠️ All theme images are now Hugo assets
 - ⚠️ Overhauled `figure` shortcode which now resizes images
-- ⚠️ Renamed parameter: `darkToggle` -> `showDarkToggle`
 - Upgrade to Tailwind v3.0.15
 - Inline Javascript moved to external files
 - Improved JSON-LD structured data

assets/js/appearance.js

@@ -0,0 +1,36 @@
+const browserIsDark =
+  window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches;
+const userPreference = localStorage.getItem("appearance");
+const switcher = document.getElementById("appearance-switcher");
+
+if (
+  (browserIsDark && userPreference === null) ||
+  (browserIsDark && userPreference === "dark") ||
+  userPreference === "dark"
+) {
+  document.documentElement.classList.add("dark");
+}
+
+if (document.documentElement.getAttribute("data-auto-appearance") === "true") {
+  window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (event) => {
+    if (event.matches) {
+      document.documentElement.classList.add("dark");
+    } else {
+      document.documentElement.classList.remove("dark");
+    }
+  });
+}
+
+window.addEventListener("DOMContentLoaded", (event) => {
+  switcher.addEventListener("click", () => {
+    document.documentElement.classList.toggle("dark");
+    localStorage.setItem(
+      "appearance",
+      document.documentElement.classList.contains("dark") ? "dark" : "light"
+    );
+  });
+  switcher.addEventListener("contextmenu", (event) => {
+    event.preventDefault();
+    localStorage.removeItem("appearance");
+  });
+});

assets/js/code.js

@@ -1,6 +1,6 @@
-var codeLang = document.getElementById("code-lang");
+var scriptBundle = document.getElementById("script-bundle");
-var copyText = codeLang ? codeLang.getAttribute("data-copy") : "Copy";
+var copyText = scriptBundle ? scriptBundle.getAttribute("data-copy") : "Copy";
-var copiedText = codeLang ? codeLang.getAttribute("data-copied") : "Copied";
+var copiedText = scriptBundle ? scriptBundle.getAttribute("data-copied") : "Copied";
 
 function createCopyButton(highlightDiv) {
   const button = document.createElement("button");

assets/js/dark.js

@@ -1,54 +0,0 @@
-function loadPreferredAppearance() {
-  if (
-    localStorage.preferredAppearance === "dark" ||
-    (!("preferredAppearance" in localStorage) &&
-      window.matchMedia("(prefers-color-scheme: dark)").matches)
-  ) {
-    document.documentElement.classList.add("dark");
-  } else {
-    document.documentElement.classList.remove("dark");
-  }
-}
-
-function setPreferredAppearance(scheme) {
-  if (scheme == "default") {
-    localStorage.removeItem("preferredAppearance");
-  } else {
-    localStorage.preferredAppearance = scheme;
-  }
-  loadPreferredAppearance();
-}
-
-window.addEventListener("DOMContentLoaded", (event) => {
-  // Hook up toggle events
-  darkToggle = document.getElementById("dark-toggle");
-  if (darkToggle) {
-    darkToggle.addEventListener("click", function (e) {
-      e.preventDefault();
-      setPreferredAppearance("dark");
-    });
-    darkToggle.addEventListener("contextmenu", function (e) {
-      e.preventDefault();
-      setPreferredAppearance("default");
-    });
-  }
-  lightToggle = document.getElementById("light-toggle");
-  if (lightToggle) {
-    lightToggle.addEventListener("click", function (e) {
-      e.preventDefault();
-      setPreferredAppearance("light");
-    });
-    lightToggle.addEventListener("contextmenu", function (e) {
-      e.preventDefault();
-      setPreferredAppearance("default");
-    });
-  }
-
-  // Load user's preset preference (if any)
-  loadPreferredAppearance();
-
-  // Allow browser media overrides
-  window
-    .matchMedia("(prefers-color-scheme: dark)")
-    .addEventListener("change", loadPreferredAppearance);
-});

config/_default/languages.en.toml

@@ -6,6 +6,7 @@ weight = 1
 rtl = false
 
 title = "Congo"
+# logo = "img/logo.jpg"
 # description = "My awesome website"
 # copyright = "Copy, _right?_ :thinking_face:"
 

config/_default/params.toml

@@ -6,13 +6,15 @@
 # https://jpanther.github.io/congo/docs/configuration/#theme-parameters
 
 colorScheme = "congo"
+defaultAppearance = "light" # valid options: light or dark
+autoSwitchAppearance = true
+showAppearanceSwitcher = false
+
 enableSearch = false
 enableCodeCopy = false
-darkMode = "auto"
+
-# logo = "img/logo.jpg"
 # mainSections = ["section1", "section2"]
 # robots = ""
-showDarkToggle = false
 showScrollToTop = true
 
 [homepage]

exampleSite/config/_default/languages.en.toml

@@ -6,6 +6,7 @@ weight = 1
 rtl = false
 
 title = "Congo"
+# logo = "img/logo.jpg"
 # description = "My awesome website"
 # copyright = "Copy, _right?_ :thinking_face:"
 

exampleSite/config/_default/params.toml

@@ -6,13 +6,15 @@
 # https://jpanther.github.io/congo/docs/configuration/#theme-parameters
 
 colorScheme = "congo"
+defaultAppearance = "light" # valid options: light or dark
+autoSwitchAppearance = true
+showAppearanceSwitcher = true
+
 enableSearch = true
 enableCodeCopy = true
-darkMode = "auto"
+
-# logo = "img/logo.jpg"
 mainSections = ["samples"]
 # robots = ""
-showDarkToggle = false
 showScrollToTop = true
 
 [homepage]

exampleSite/content/docs/configuration.md

@@ -99,13 +99,14 @@ Many of the article defaults here can be overridden on a per article basis by sp
 |Name|Default|Description|
 |---|---|---|
 |`colorScheme`|`"congo"`|The theme colour scheme to use. Valid values are `congo` (default), `avocado`, `ocean`, `fire` and `slate`. Refer to the [Colour Schemes]({{< ref "getting-started#colour-schemes" >}}) section for more details.|
+|`defaultAppearance`|`"light"`|The default theme appearance, either `light` or `dark`.|
+|`autoSwitchAppearance`|`true`|Whether the theme appearance automatically switches based upon the visitor's operating system preference. Set to `false` to force the site to always use the `defaultAppearance`.|
+|`showAppearanceSwitcher`|`false`|Whether or not to show the appearance switcher in the site footer. The browser's local storage is used to persist the visitor's preference.|
 |`enableSearch`|`false`|Whether site search is enabled. Set to `true` to enable search functionality. Note that the search feature depends on the `outputs.home` setting in the [site configuration](#site-configuration) being set correctly.|
-|`enableCodeCopy`|`false`|Whether copy buttons are enabled for `<code>` blocks.|
+|`enableCodeCopy`|`false`|Whether copy-to-clipboard buttons are enabled for `<code>` blocks.|
-|`darkMode`|`"auto"`|The preferred theme appearance for dark mode. Set to `true` to force dark appearance or `false` to force light appearance. Using `"auto"` will defer to the user's operating system preference.|
 |`logo`|_Not set_|The relative path to the site logo file within the `assets/` folder. The logo file should be provided at 2x resolution and supports any image dimensions.|
 |`mainSections`|_Not set_|The sections that should be displayed in the recent articles list. If not provided the section with the greatest number of articles is used.|
 |`robots`|_Not set_|String that indicates how robots should handle your site. If set, it will be output in the page head. Refer to [Google's docs](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives) for valid values.|
-|`showDarkToggle`|`false`|When `darkMode` is set to `"auto"`, this parameter determines whether or not to show the appearance toggle in the site footer. The browser's local storage is used to persist the user's preference.|
 |`showScrollToTop`|`true`|When set to `true` the scroll to top arrow is displayed.|
 |`homepage.layout`|`"page"`|The layout of the homepage. Valid values are `page`, `profile` or `custom`. When set to `custom`, you must provide your own layout by creating a `/layouts/partials/home/custom.html` file. Refer to the [Homepage Layout]({{< ref "homepage-layout" >}}) section for more details.|
 |`homepage.showRecent`|`false`|Whether or not to display the recent articles list on the homepage.|

exampleSite/content/docs/installation.md

@@ -20,7 +20,7 @@ These instructions will get you up and running using Hugo and Congo from a compl
 If you haven't used Hugo before, you will need to [install it onto your local machine](https://gohugo.io/getting-started/installing). You can check if it's already installed by running the command `hugo version`.
 
 {{< alert >}}
-Make sure you are using **Hugo version 0.86.1** or later as the theme takes advantage of some of the latest Hugo features.
+Make sure you are using **Hugo version 0.87.0** or later as the theme takes advantage of some of the latest Hugo features.
 {{< /alert >}}
 
 You can find detailed installation instructions for your platform in the [Hugo docs](https://gohugo.io/getting-started/installing).

exampleSite/content/docs/version-2/_index.md

@@ -28,7 +28,7 @@ A highly requested feature, Congo is now multilingual! If you publish your conte
 
 <div class="text-2xl text-center" style="font-size: 2.8rem">:flag-au: :de: :fr: :es: :cn: :brazil: :tr:</div>
 
-Thanks to submissions from the community, Congo has already been translated into [seven languages](https://github.com/jpanther/congo/tree/dev/i18n) with more to be added over time. By the way, pull requests for new languages are always welcome!
+Thanks to submissions from the community, Congo has already been translated into [seven languages](https://github.com/jpanther/congo/tree/dev/i18n) with more to be added over time. By the way, [pull requests](https://github.com/jpanther/congo/pulls) for new languages are always welcome!
 
 ## RTL language support
 
@@ -87,6 +87,10 @@ The new image resizing features also provide full control over `alt` and `title`
 
 There's countless other minor changes to explore. From being able to display taxonomies on articles and list pages, to using the new `headline` author parameter to customise your homepage. There's also improved JSON-LD strucured data which further optimises SEO performance. Plus the entire theme has had extra polish to ensure a consistent design language.
 
+:rocket: Check out the [full changelog](https://github.com/jpanther/congo/blob/dev/CHANGELOG.md) to learn more.
+
+## Next steps
+
 If you're ready to upgrade, read the [upgrading from version 1 guide]({{< ref "upgrade" >}}) to get started. If you're new to Congo, check out the [Installation guide]({{< ref "docs/installation" >}}) to begin a new project.
 
 ---

exampleSite/content/docs/version-2/upgrade/index.md

@@ -117,6 +117,11 @@ If you're using a language other than English, provide a `defaultContentLanguage
 # config/_default/config.toml
 
 defaultContentLanguage = "en"
+
+enableRobotsTXT = true
+paginate = 10
+summaryLength = 0
+
 [outputs]
   home = ["HTML", "RSS", "JSON"]
 ```
@@ -139,11 +144,17 @@ The recommended settings are as follows, which includes any headings in the Mark
 
 A number of new theme parameters have been introduced in Congo 2.0. Some minor changes are requried to existing configurations. Remember, the theme will always revert to a sensible default if a parameter is not provided.
 
-The follow parameters have been **renamed**:
+The way that dark mode works in Congo has been changed to allow greater flexibility around configuration. The old `darkMode` and `darkToggle` parameters have been **removed and replaced** by three new parameters. These new options operate independently of each other, making it possible to force the appearance while still allowing the user to override.
 
-`darkToggle` **→** `showDarkToggle`
+<!-- prettier-ignore-start -->
+| New parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultAppearance` | String | `"light"` | Default theme appearance; either `light` or `dark`.<br>:warning: _Setting this to `light` replicates the old `darkMode = false` setting, while `dark` replicates `darkMode = true`._ |
+| `autoSwitchAppearance` | Boolean | `true` | Whether the theme appearance automatically switches based upon the operating system preference. Set to `false` to force the site to always use the `defaultAppearance`. <br>:warning: _Setting this to `true` replicates the old `darkMode = "auto"` setting._ |
+| `showAppearanceSwitcher` | Boolean | `false` | Whether the theme appearance switcher is dispalyed in the site footer. <br>:warning: _This parameter replaces `darkToggle`._ |
+<!-- prettier-ignore-end -->
 
-The following table outlines some key **new parameters** that control new features in version 2:
+The following table outlines some other key **new parameters** that control new features in version 2:
 
 | New parameter                 | Type    | Default |
 | ----------------------------- | ------- | ------- |

layouts/_default/baseof.html

@@ -8,7 +8,10 @@
   {{- else -}}
     ltr
   {{- end }}"
-  class="scroll-smooth {{ if .Site.Params.darkMode | default false }}dark{{ end }}"
+  class="scroll-smooth {{ if eq (.Site.Params.defaultAppearance | default "light") "dark" -}}
+    dark
+  {{- end }}"
+  data-auto-appearance="{{ .Site.Params.autoSwitchAppearance | default "true" }}"
 >
   {{- partial "head.html" . -}}
   <body

layouts/partials/footer.html

@@ -39,26 +39,21 @@
         </p>
       {{ end }}
     </div>
-    {{/* Dark mode toggle */}}
+    {{/* Appearance switch */}}
-    {{ if and (.Site.Params.showDarkToggle | default false) (eq (.Site.Params.darkMode | default "auto") "auto") }}
+    {{ if .Site.Params.showAppearanceSwitcher | default false }}
       <div
         class="text-sm cursor-pointer text-neutral-700 dark:text-neutral hover:text-primary-600 dark:hover:text-primary-400 {{ if .Site.Params.showScrollToTop | default true -}}
           ltr:mr-14 rtl:ml-14
         {{- end }}"
       >
         <button
-          id="dark-toggle"
+          id="appearance-switcher"
-          class="inline w-12 h-12 dark:hidden"
+          class="w-12 h-12 "
+          type="button"
           title="{{ i18n "footer.dark_appearance" }}"
         >
-          {{ partial "icon.html" "moon" }}
+          <span class="inline dark:hidden">{{ partial "icon.html" "moon" }}</span>
-        </button>
+          <span class="hidden dark:inline">{{ partial "icon.html" "sun" }}</span>
-        <button
-          id="light-toggle"
-          class="hidden w-12 h-12 cursor-pointer dark:inline"
-          title="{{ i18n "footer.light_appearance" }}"
-        >
-          {{ partial "icon.html" "sun" }}
         </button>
       </div>
     {{ end }}

layouts/partials/head.html

@@ -50,9 +50,9 @@
     href="{{ $bundleCSS.RelPermalink }}"
     integrity="{{ $bundleCSS.Data.Integrity }}"
   />
-  {{ if eq (.Site.Params.darkMode | default "auto") "auto" }}
+  {{ if .Site.Params.enableAppearanceSwitching | default true }}
-    {{ $jsDark := resources.Get "js/dark.js" }}
+    {{ $jsAppearance := resources.Get "js/appearance.js" }}
-    {{ $assets.Add "js" (slice $jsDark) }}
+    {{ $assets.Add "js" (slice $jsAppearance) }}
   {{ end }}
   {{ if .Site.Params.enableSearch | default false }}
     {{ $jsFuse := resources.Get "lib/fuse/fuse.min.js" }}
@@ -62,11 +62,10 @@
   {{ if .Site.Params.enableCodeCopy | default false }}
     {{ $jsCode := resources.Get "js/code.js" }}
     {{ $assets.Add "js" (slice $jsCode) }}
-    <script type="application/json" id="code-lang" data-copy="{{ i18n "code.copy" }}" data-copied="{{ i18n "code.copied" }}"></script>
   {{ end }}
   {{ if $assets.Get "js" }}
     {{ $bundleJS := $assets.Get "js" | resources.Concat "js/main.bundle.js" | resources.Minify | resources.Fingerprint "sha512" }}
-    <script defer type="text/javascript" src="{{ $bundleJS.RelPermalink }}" integrity="{{ $bundleJS.Data.Integrity }}"></script>
+    <script defer type="text/javascript" id="script-bundle" src="{{ $bundleJS.RelPermalink }}" integrity="{{ $bundleJS.Data.Integrity }}" data-copy="{{ i18n "code.copy" }}" data-copied="{{ i18n "code.copied" }}"></script>
   {{ end }}
   {{/* Icons */}}
   {{ if templates.Exists "partials/favicons.html" }}