migrate to decoupled Blowfish layout, fix TOC scrollspy, and update docs

- Theme Decoupling & Cleanup:
      - Fully decoupled and vendored the Blowfish theme directly into root directories (layouts/,
  assets/, static/, data/, i18n/).
      - De-registered and cleaned up legacy Git submodules (themes/blowfish, themes/hugo-admonitions)
  from the Git index to protect the build from upstream breakages.
      - Configured .gitignore to ignore development preview symlinks (content, static,
  config/_default/menus.en.toml), build folders (public/, resources/), and locks.

    - TOC & Layout Fixes:
      - Replaced the custom layouts/_default/single.html template with the Blowfish default to restore
  native container widths and the side-by-side flex layout.
      - Restored TOC to float on the right sidebar on desktop viewports and render inline on mobile
  viewports.
      - Fixed a parameter resolution bug in layouts/partials/toc.html by checking both .Site.Params.
  smartTOC and .Site.Params.article.smartTOC (where it is defined in params.toml).
      - Upgraded the TOC scrollspy JavaScript to target all '#TableOfContents' containers on the page,
  enabling highlight tracking on both desktop and mobile layouts.

    - Documentation Updates (README.md):
      - Restored YAML front matter metadata block at the top.
      - Added detailed notes on the CI/CD build process and Gitea runner deployment targets
  (/srv/www/docs-public and /srv/www/docs-private).
      - Added a categorized and sorted "Shortcodes Quick Reference" table at the top of the shortcodes
  section (ordered by Custom, Hugo Default, and Blowfish).
      - Documented custom shortcodes (Include, Screenshot, Raw HTML) and missing Hugo default
  shortcodes (Highlight, Instagram, Param, Ref, Relref, Twitter, Vimeo, Youtube).
      - Restructured headings to ensure all sub-shortcodes are H3, removed block break tags (<br/>),
  and appended horizontal separators (---) after H2 sections.

assets/js/appearance.js

@@ -0,0 +1,144 @@
+const sitePreference = document.documentElement.getAttribute("data-default-appearance");
+const userPreference = localStorage.getItem("appearance");
+
+if ((sitePreference === "dark" && userPreference === null) || userPreference === "dark") {
+  document.documentElement.classList.add("dark");
+}
+
+if (document.documentElement.getAttribute("data-auto-appearance") === "true") {
+  if (
+    window.matchMedia &&
+    window.matchMedia("(prefers-color-scheme: dark)").matches &&
+    userPreference !== "light"
+  ) {
+    document.documentElement.classList.add("dark");
+  }
+  window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (event) => {
+    if (event.matches) {
+      document.documentElement.classList.add("dark");
+    } else {
+      document.documentElement.classList.remove("dark");
+    }
+  });
+}
+
+// Mermaid dark mode support
+var updateMermaidTheme = () => {
+  if (typeof mermaid !== 'undefined') {
+    const isDark = document.documentElement.classList.contains("dark");
+
+    const mermaids = document.querySelectorAll('pre.mermaid');
+    mermaids.forEach(e => {
+      if (e.getAttribute('data-processed')) {
+        // Already rendered, clean the processed attributes
+        e.removeAttribute('data-processed');
+        // Replace the rendered HTML with the stored text
+        e.innerHTML = e.getAttribute('data-graph');
+      } else {
+        // First time, store the text
+        e.setAttribute('data-graph', e.textContent);
+      }
+    });
+
+    if (isDark) {
+      initMermaidDark();
+      mermaid.run();
+    } else {
+      initMermaidLight();
+      mermaid.run();
+    }
+  }
+}
+
+window.addEventListener("DOMContentLoaded", (event) => {
+  const switcher = document.getElementById("appearance-switcher");
+  const switcherMobile = document.getElementById("appearance-switcher-mobile");
+
+  updateMeta();
+  this.updateLogo?.(getTargetAppearance());
+
+  // Initialize mermaid theme on page load
+  updateMermaidTheme();
+
+  if (switcher) {
+    switcher.addEventListener("click", () => {
+      document.documentElement.classList.toggle("dark");
+      var targetAppearance = getTargetAppearance();
+      localStorage.setItem(
+        "appearance",
+        targetAppearance
+      );
+      updateMeta();
+      updateMermaidTheme();
+      this.updateLogo?.(targetAppearance);
+    });
+    switcher.addEventListener("contextmenu", (event) => {
+      event.preventDefault();
+      localStorage.removeItem("appearance");
+    });
+  }
+  if (switcherMobile) {
+    switcherMobile.addEventListener("click", () => {
+      document.documentElement.classList.toggle("dark");
+      var targetAppearance = getTargetAppearance();
+      localStorage.setItem(
+        "appearance",
+        targetAppearance
+      );
+      updateMeta();
+      updateMermaidTheme();
+      this.updateLogo?.(targetAppearance);
+    });
+    switcherMobile.addEventListener("contextmenu", (event) => {
+      event.preventDefault();
+      localStorage.removeItem("appearance");
+    });
+  }
+});
+
+
+var updateMeta = () => {
+  var elem, style;
+  elem = document.querySelector('body');
+  style = getComputedStyle(elem);
+  document.querySelector('meta[name="theme-color"]').setAttribute('content', style.backgroundColor);
+}
+
+{{ if and (.Site.Params.Logo) (.Site.Params.SecondaryLogo) }}
+{{ $primaryLogo := resources.Get .Site.Params.Logo }}
+{{ $secondaryLogo := resources.Get .Site.Params.SecondaryLogo }}
+{{ if and ($primaryLogo) ($secondaryLogo) }}
+var updateLogo = (targetAppearance) => {
+  var imgElems = document.querySelectorAll("img.logo");
+  var logoContainers = document.querySelectorAll("span.logo");
+  
+  targetLogoPath = 
+    targetAppearance == "{{ .Site.Params.DefaultAppearance }}" ?
+    "{{ $primaryLogo.RelPermalink }}" : "{{ $secondaryLogo.RelPermalink }}"
+  for (const elem of imgElems) {
+    elem.setAttribute("src", targetLogoPath)
+  }
+
+  {{ if eq $primaryLogo.MediaType.SubType "svg" }}
+  targetContent = 
+    targetAppearance == "{{ .Site.Params.DefaultAppearance }}" ?
+    `{{ $primaryLogo.Content | safeHTML }}` : `{{ $secondaryLogo.Content | safeHTML }}`
+  for (const container of logoContainers) {
+    container.innerHTML = targetContent;
+  }
+  {{ end }}
+}
+{{ end }}
+{{- end }}
+
+var getTargetAppearance = () => {
+  return document.documentElement.classList.contains("dark") ? "dark" : "light"
+}
+
+window.addEventListener("DOMContentLoaded", (event) => {
+  const scroller = document.getElementById("top-scroller");
+  const footer = document.getElementById("site-footer");
+  if(scroller && footer && scroller.getBoundingClientRect().top > footer.getBoundingClientRect().top) {
+    scroller.hidden = true;
+  }
+});