feat: add giscus theme customization (#522)

Co-authored-by: Xin <xin@imfing.com>

assets/js/sidebar.js

@@ -1,42 +1,7 @@
 document.addEventListener("DOMContentLoaded", function () {
-  initializeSidebar();
+  scrollToActiveItem();
-});
-
-function initializeSidebar() {
-  const sidebarScrollbar = document.querySelector("aside.sidebar-container > .hextra-scrollbar");
-  if (!sidebarScrollbar) return;
-
   enableCollapsibles();
-  restoreSidebarPosition(sidebarScrollbar);
+});
-
-  const debouncedSave = debounce((position) => {
-    saveSidebarPosition(position);
-  }, 150);
-  
-  sidebarScrollbar.addEventListener('scroll', function() {
-    debouncedSave(this.scrollTop);
-  });
-
-  document.querySelectorAll('a').forEach(link => {
-    if (link.hostname === window.location.hostname) {
-      link.addEventListener('click', function(e) {
-        saveSidebarPosition(sidebarScrollbar.scrollTop);
-      });
-    }
-  });
-}
-
-function debounce(func, wait) {
-  let timeout;
-  return function executedFunction(...args) {
-    const later = () => {
-      clearTimeout(timeout);
-      func(...args);
-    };
-    clearTimeout(timeout);
-    timeout = setTimeout(later, wait);
-  };
-}
 
 function enableCollapsibles() {
   const buttons = document.querySelectorAll(".hextra-sidebar-collapsible-button");
@@ -51,16 +16,21 @@ function enableCollapsibles() {
   });
 }
 
-function saveSidebarPosition(scrollPosition) {
+function scrollToActiveItem() {
-  localStorage.setItem('sidebarScrollPosition', scrollPosition);
+  const sidebarScrollbar = document.querySelector("aside.sidebar-container > .hextra-scrollbar");
-}
+  const activeItems = document.querySelectorAll(".sidebar-active-item");
+  const visibleActiveItem = Array.from(activeItems).find(function (activeItem) {
+    return activeItem.getBoundingClientRect().height > 0;
+  });
 
-function restoreSidebarPosition(sidebarScrollbar) {
+  if (!visibleActiveItem) {
-  const savedPosition = localStorage.getItem('sidebarScrollPosition');
+    return;
-  
-  if (savedPosition !== null) {
-    requestAnimationFrame(() => {
-      sidebarScrollbar.scrollTop = parseInt(savedPosition);
-    });
   }
-}
+
+  const yOffset = visibleActiveItem.clientHeight;
+  const yDistance = visibleActiveItem.getBoundingClientRect().top - sidebarScrollbar.getBoundingClientRect().top;
+  sidebarScrollbar.scrollTo({
+    behavior: "instant",
+    top: yDistance - yOffset
+  });
+}

exampleSite/content/docs/advanced/customization.md

@@ -44,6 +44,129 @@ The primary color of the theme can be customized by setting the `--primary-hue`,
 }
 ```
 
+### Further Theme Customization
+
+The theme can be further customized by overriding the default styles via the exposed css classes. An example for customizing the footer element:
+
+```css {filename="assets/css/custom.css"}
+.hextra-footer {
+  /* Styles will be applied to the footer element */
+}
+
+.hextra-footer:is(html[class~="dark"] *) {
+  /* Styles will be applied to the footer element in dark mode */
+}
+
+```
+
+The following classes can be used to customize various parts of the theme.
+
+#### General
+
+- `hextra-scrollbar` - The scrollbar element
+- `content` - Page content container
+
+#### Shortcodes
+
+##### Badge
+
+- `hextra-badge` - The badge element
+
+##### Card
+
+- `hextra-card` - The card element
+- `hextra-card-image` - The card image element
+- `hextra-card-icon` - The card icon element
+- `hextra-card-subtitle` - The card subtitle element
+
+##### Cards
+
+- `hextra-cards` - The cards grid container
+
+##### Jupyter Notebook
+
+- `hextra-jupyter-code-cell` - The Jupyter code cell container
+- `hextra-jupyter-code-cell-outputs-container` - The Jupyter code cell outputs container
+- `hextra-jupyter-code-cell-outputs` - The Jupyter code cell output div element
+
+##### PDF
+
+- `hextra-pdf` - The PDF container element
+
+##### Steps
+
+- `steps` - The steps container
+
+##### Tabs
+
+- `hextra-tabs-panel` - The tabs panel container
+- `hextra-tabs-toggle` - The tabs toggle button
+
+##### Filetree
+
+- `hextra-filetree` - The filetree container
+
+##### Folder
+
+- `hextra-filetree-folder` - The filetree folder container
+
+#### Navbar
+
+- `nav-container` - The navbar container
+- `nav-container-blur` - The navbar container in blur element
+- `hamburger-menu` - The hamburger menu button
+
+#### Footer
+
+- `hextra-footer` - The footer element
+- `hextra-custom-footer` - The custom footer section container
+
+#### Search
+
+- `search-wrapper` - The search wrapper container
+- `search-input` - The search input element
+- `search-results` - The search results list container
+
+#### Table of Contents
+
+- `hextra-toc` - The table of contents container
+
+#### Sidebar
+
+- `mobile-menu-overlay` - The overlay element for the mobile menu
+- `sidebar-container` - The sidebar container
+- `sidebar-active-item` - The active item in the sidebar
+
+#### Language Switcher
+
+- `language-switcher` - The language switcher button
+- `language-options` - The language options container
+
+#### Theme Toggle
+
+- `theme-toggle` - The theme toggle button
+
+#### Cody Copy Button
+
+- `hextra-code-copy-btn-container` - The code copy button container
+- `hextra-code-copy-btn` - The code copy button
+
+#### Code Block
+
+- `hextra-code-block` - The code block container
+
+#### Feature Card
+
+- `hextra-feature-card` - The feature card link element
+
+#### Feature Grid
+
+- `hextra-feature-grid` - The feature grid container
+
+#### Breadcrumbs
+
+No specific class is available for breadcrumbs.
+
 ### Syntax Highlighting
 
 List of available syntax highlighting themes are available at [Chroma Styles Gallery](https://xyproto.github.io/splash/docs/all.html). The stylesheet can be generated using the command:
@@ -62,6 +185,21 @@ You may add custom scripts to the end of the head for every page by adding the f
 layouts/partials/custom/head-end.html
 ```
 
+## Custom Footer Section
+
+You can add a custom section the footer between the language/theme buttons and the "Copyright"/"Powered By" section by creating a file `layouts/partials/custom/footer.html` in your site.
+
+```html {filename="layouts/partials/custom/footer.html"}
+<!-- Your footer element here -->
+```
+
+Available variables in the footer section are:
+
+- `.switchesVisible`: `true` if the language/theme button(s) are visible above the footer along with a horizontal separator.
+- `.copyrightVisible`: `true` if the "Copyright" and "Powered By" text are visible at the bottom of the footer.
+
+_Note: The custom footer inherits the default footer background color text color and the `width` setting in `hugo.yaml#footer` section._
+
 ## Custom Layouts
 
 The layouts of the theme can be overridden by creating a file with the same name in the `layouts` directory of your site.

exampleSite/content/showcase/index.md

@@ -95,7 +95,7 @@ Open source projects powered by Hextra
   >}}
 
   {{< card
-        link="https://lutheranconfessions.org/"
+        link="https://github.com/remysheppard/lutheran-confessions"
         title="LutheranConfessions"
         image="https://github.com/imfing/hextra/assets/5097752/ad6625e4-88cd-4cad-b102-5399997d0359"
         imageStyle="object-fit:cover; aspect-ratio:16/9;"

exampleSite/hugo.yaml

@@ -173,3 +173,4 @@ params:
       # emitMetadata: 0
       # inputPosition: top
       # lang: en
+      # theme: noborder_dark

exampleSite/hugo_stats.json

@@ -228,6 +228,7 @@
       "hextra-code-block",
       "hextra-code-copy-btn",
       "hextra-code-copy-btn-container",
+      "hextra-custom-footer",
       "hextra-feature-card",
       "hextra-feature-grid",
       "hextra-filetree",

layouts/partials/components/giscus.html

@@ -8,9 +8,18 @@
    * This solution was created with reference to:
    * https://github.com/giscus/giscus/issues/336#issuecomment-1214366281
   */
-  function getGiscusTheme() {
+  function getHugoTheme() {
     return localStorage.getItem("color-theme");
   }
+  
+  function getGiscusTheme() {
+    let giscusTheme = "{{ (string .theme) | default `light` }}";
+    if(getHugoTheme() == 'light') {
+      return giscusTheme.replace('dark', 'light');
+    } else {
+      return giscusTheme.replace('light', 'dark');
+    }
+  }
 
   function setGiscusTheme() {
     function sendMessage(message) {

layouts/partials/footer.html

@@ -1,5 +1,7 @@
 {{- $enableFooterSwitches := .Scratch.Get "enableFooterSwitches" | default false -}}
 {{- $displayThemeToggle := site.Params.theme.displayToggle | default true -}}
+{{- $footerSwitchesVisible := and $enableFooterSwitches (or hugo.IsMultilingual $displayThemeToggle) -}}
+{{- $copyrightSectionVisible := or (.Site.Params.footer.displayPoweredBy | default true) .Site.Params.footer.displayCopyright -}}
 
 {{- $copyright := (T "copyright") | default "© 2024 Hextra." -}}
 {{- $poweredBy := (T "poweredBy") | default "Powered by Hextra" -}}
@@ -15,7 +17,7 @@
 
 
 <footer class="hextra-footer hx-bg-gray-100 hx-pb-[env(safe-area-inset-bottom)] dark:hx-bg-neutral-900 print:hx-bg-transparent">
-  {{- if $enableFooterSwitches -}}
+  {{- if $footerSwitchesVisible -}}
     <div class="hx-mx-auto hx-flex hx-gap-2 hx-py-2 hx-px-4 {{ $footerWidth }}">
       {{- partial "language-switch.html" (dict "context" .) -}}
       {{- with $displayThemeToggle }}{{ partial "theme-toggle.html" }}{{ end -}}
@@ -24,14 +26,21 @@
       <hr class="dark:hx-border-neutral-800" />
     {{- end -}}
   {{- end -}}
-  <div
+    <div
-    class="{{ $footerWidth }} hx-mx-auto hx-flex hx-justify-center hx-py-12 hx-pl-[max(env(safe-area-inset-left),1.5rem)] hx-pr-[max(env(safe-area-inset-right),1.5rem)] hx-text-gray-600 dark:hx-text-gray-400 md:hx-justify-start"
+      class="hextra-custom-footer {{ $footerWidth }} hx-pl-[max(env(safe-area-inset-left),1.5rem)] hx-pr-[max(env(safe-area-inset-right),1.5rem)] hx-text-gray-600 dark:hx-text-gray-400"
-  >
+    >
-    <div class="hx-flex hx-w-full hx-flex-col hx-items-center sm:hx-items-start">
+      {{- partial "custom/footer.html" (dict "context" . "switchesVisible" $footerSwitchesVisible "copyrightVisible" $copyrightSectionVisible) -}}
-      {{- if (.Site.Params.footer.displayPoweredBy | default true) }}<div class="hx-font-semibold">{{ template "theme-credit" $poweredBy }}</div>{{ end }}
-      {{- if .Site.Params.footer.displayCopyright }}<div class="hx-mt-6 hx-text-xs">{{ $copyright | markdownify }}</div>{{ end }}
     </div>
-  </div>
+    {{- if $copyrightSectionVisible -}}
+      <div
+        class="{{ $footerWidth }} hx-mx-auto hx-flex hx-justify-center hx-py-12 hx-pl-[max(env(safe-area-inset-left),1.5rem)] hx-pr-[max(env(safe-area-inset-right),1.5rem)] hx-text-gray-600 dark:hx-text-gray-400 md:hx-justify-start"
+      >
+        <div class="hx-flex hx-w-full hx-flex-col hx-items-center sm:hx-items-start">
+            {{- if (.Site.Params.footer.displayPoweredBy | default true) }}<div class="hx-font-semibold">{{ template "theme-credit" $poweredBy }}</div>{{- end -}}
+            {{- if .Site.Params.footer.displayCopyright }}<div class="hx-mt-6 hx-text-xs">{{ $copyright | markdownify }}</div>{{- end -}}
+        </div>
+      </div>
+    {{- end -}}
 </footer>
 
 {{- define "theme-credit" -}}